diff --git a/en/resources/beta/index.md b/en/resources/beta/index.md index e49b6673..a28a6ab4 100644 --- a/en/resources/beta/index.md +++ b/en/resources/beta/index.md @@ -1,7832 +1,8449 @@ # Beta -# Responses - -## Create a model response - -**post** `/responses?beta=true` - -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. +# Assistants -### Header Parameters +## Create assistant -- `"openai-beta": optional array of "responses_multi_agent=v1"` +**post** `/assistants` - - `"responses_multi_agent=v1"` +Create an assistant with a model and instructions. ### Body Parameters -- `background: optional boolean` +- `model: string or "gpt-5" or "gpt-5-mini" or "gpt-5-nano" or 39 more` - Whether to run the model response in the background. - [Learn more](/docs/guides/background). + ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](/docs/models) for descriptions of them. -- `context_management: optional array of object { type, compact_threshold }` + - `string` - Context management configuration for this request. + - `AssistantSupportedModels = "gpt-5" or "gpt-5-mini" or "gpt-5-nano" or 39 more` - - `type: string` + ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](/docs/models) for descriptions of them. - The context management entry type. Currently only 'compaction' is supported. + - `"gpt-5"` - - `compact_threshold: optional number` + - `"gpt-5-mini"` - Token threshold at which compaction should be triggered for this entry. + - `"gpt-5-nano"` -- `conversation: optional string or BetaResponseConversationParam` + - `"gpt-5-2025-08-07"` - 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. + - `"gpt-5-mini-2025-08-07"` - - `ConversationID = string` + - `"gpt-5-nano-2025-08-07"` - The unique ID of the conversation. + - `"gpt-4.1"` - - `BetaResponseConversationParam object { id }` + - `"gpt-4.1-mini"` - The conversation that this response belongs to. + - `"gpt-4.1-nano"` - - `id: string` + - `"gpt-4.1-2025-04-14"` - The unique ID of the conversation. + - `"gpt-4.1-mini-2025-04-14"` -- `include: optional array of BetaResponseIncludable` + - `"gpt-4.1-nano-2025-04-14"` - Specify additional output data to include in the model response. Currently supported values are: + - `"o3-mini"` - - `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). + - `"o3-mini-2025-01-31"` - - `"file_search_call.results"` + - `"o1"` - - `"web_search_call.results"` + - `"o1-2024-12-17"` - - `"web_search_call.action.sources"` + - `"gpt-4o"` - - `"message.input_image.image_url"` + - `"gpt-4o-2024-11-20"` - - `"computer_call_output.output.image_url"` + - `"gpt-4o-2024-08-06"` - - `"code_interpreter_call.outputs"` + - `"gpt-4o-2024-05-13"` - - `"reasoning.encrypted_content"` + - `"gpt-4o-mini"` - - `"message.output_text.logprobs"` + - `"gpt-4o-mini-2024-07-18"` -- `input: optional string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + - `"gpt-4.5-preview"` - Text, image, or file inputs to the model, used to generate a response. + - `"gpt-4.5-preview-2025-02-27"` - Learn more: + - `"gpt-4-turbo"` - - [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) + - `"gpt-4-turbo-2024-04-09"` - - `TextInput = string` + - `"gpt-4-0125-preview"` - A text input to the model, equivalent to a text input with the - `user` role. + - `"gpt-4-turbo-preview"` - - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + - `"gpt-4-1106-preview"` - A list of one or many input items to the model, containing - different content types. + - `"gpt-4-vision-preview"` - - `BetaEasyInputMessage object { content, role, phase, type }` + - `"gpt-4"` - 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. + - `"gpt-4-0314"` - - `content: string or BetaResponseInputMessageContentList` + - `"gpt-4-0613"` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `"gpt-4-32k"` - - `TextInput = string` + - `"gpt-4-32k-0314"` - A text input to the model. + - `"gpt-4-32k-0613"` - - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` + - `"gpt-3.5-turbo"` - A list of one or many input items to the model, containing different content - types. + - `"gpt-3.5-turbo-16k"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `"gpt-3.5-turbo-0613"` - A text input to the model. + - `"gpt-3.5-turbo-1106"` - - `text: string` + - `"gpt-3.5-turbo-0125"` - The text input to the model. + - `"gpt-3.5-turbo-16k-0613"` - - `type: "input_text"` +- `description: optional string` - The type of the input item. Always `input_text`. + The description of the assistant. The maximum length is 512 characters. - - `"input_text"` +- `instructions: optional string` - - `prompt_cache_breakpoint: optional object { mode }` + The system instructions that the assistant uses. The maximum length is 256,000 characters. - 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. +- `metadata: optional Metadata` - - `mode: "explicit"` + 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 breakpoint mode. Always `explicit`. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"explicit"` +- `name: optional string` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + The name of the assistant. The maximum length is 256 characters. - An image input to the model. Learn about [image inputs](/docs/guides/vision). +- `reasoning_effort: optional ReasoningEffort` - - `detail: "low" or "high" or "auto" or "original"` + 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 detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"none"` + + - `"minimal"` - `"low"` + - `"medium"` + - `"high"` - - `"auto"` + - `"xhigh"` - - `"original"` + - `"max"` - - `type: "input_image"` +- `response_format: optional AssistantResponseFormatOption` - The type of the input item. Always `input_image`. + Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `"input_image"` + Setting to `{ "type": "json_schema", "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` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - The ID of the file to be sent to the model. + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `image_url: optional string` + - `"auto"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + `auto` is the default value - - `prompt_cache_breakpoint: optional object { mode }` + - `"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. + - `ResponseFormatText object { type }` - - `mode: "explicit"` + Default response format. Used to generate text responses. - The breakpoint mode. Always `explicit`. + - `type: "text"` - - `"explicit"` + The type of response format being defined. Always `text`. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `"text"` - A file input to the model. + - `ResponseFormatJSONObject object { type }` - - `type: "input_file"` + 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 input item. Always `input_file`. + - `type: "json_object"` - - `"input_file"` + The type of response format being defined. Always `json_object`. - - `detail: optional "auto" or "low" or "high"` + - `"json_object"` - 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`. + - `ResponseFormatJSONSchema object { json_schema, type }` - - `"auto"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `"low"` + - `json_schema: object { name, description, schema, strict }` - - `"high"` + Structured Outputs configuration options, including a JSON Schema. - - `file_data: optional string` + - `name: string` - The content of the file to be sent to the model. + 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. - - `file_id: optional string` + - `description: optional string` - The ID of the file to be sent to the model. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `file_url: optional string` + - `schema: optional map[unknown]` - The URL of the file to be sent to the model. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `filename: optional string` + - `strict: optional boolean` - The name of the file to be sent 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). - - `prompt_cache_breakpoint: optional object { mode }` + - `type: "json_schema"` - 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 type of response format being defined. Always `json_schema`. - - `mode: "explicit"` + - `"json_schema"` - The breakpoint mode. Always `explicit`. +- `temperature: optional number` - - `"explicit"` + 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. - - `role: "user" or "assistant" or "system" or "developer"` +- `tool_resources: optional object { code_interpreter, file_search }` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - - `"user"` + - `code_interpreter: optional object { file_ids }` - - `"assistant"` + - `file_ids: optional array of string` - - `"system"` + A list of [file](/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. - - `"developer"` + - `file_search: optional object { vector_store_ids, vector_stores }` - - `phase: optional "commentary" or "final_answer"` + - `vector_store_ids: optional array of 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 [vector store](/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. - - `"commentary"` + - `vector_stores: optional array of object { chunking_strategy, file_ids, metadata }` - - `"final_answer"` + A helper to create a [vector store](/docs/api-reference/vector-stores/object) with file_ids and attach it to this assistant. There can be a maximum of 1 vector store attached to the assistant. - - `type: optional "message"` + - `chunking_strategy: optional object { type } or object { static, type }` - The type of the message input. Always `message`. + The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. - - `"message"` + - `Auto object { type }` - - `Message object { content, role, agent, 2 more }` + The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`. - 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: "auto"` - - `content: BetaResponseInputMessageContentList` + Always `auto`. - A list of one or many input items to the model, containing different content - types. + - `"auto"` - - `role: "user" or "system" or "developer"` + - `Static object { static, type }` - The role of the message input. One of `user`, `system`, or `developer`. + - `static: object { chunk_overlap_tokens, max_chunk_size_tokens }` - - `"user"` + - `chunk_overlap_tokens: number` - - `"system"` + The number of tokens that overlap between chunks. The default value is `400`. - - `"developer"` + Note that the overlap must not exceed half of `max_chunk_size_tokens`. - - `agent: optional object { agent_name }` + - `max_chunk_size_tokens: number` - The agent that produced this item. + The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`. - - `agent_name: string` + - `type: "static"` - The canonical name of the agent that produced this item. + Always `static`. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"static"` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `file_ids: optional array of string` - - `"in_progress"` + A list of [file](/docs/api-reference/files) IDs to add to the vector store. For vector stores created before Nov 2025, there can be a maximum of 10,000 files in a vector store. For vector stores created starting in Nov 2025, the limit is 100,000,000 files. - - `"completed"` + - `metadata: optional Metadata` - - `"incomplete"` + 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. - - `type: optional "message"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The type of the message input. Always set to `message`. +- `tools: optional array of CodeInterpreterTool or FileSearchTool or FunctionTool` - - `"message"` + A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + - `CodeInterpreterTool object { type }` - An output message from the model. + - `type: "code_interpreter"` - - `id: string` + The type of tool being defined: `code_interpreter` - The unique ID of the output message. + - `"code_interpreter"` - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `FileSearchTool object { type, file_search }` - The content of the output message. + - `type: "file_search"` - - `BetaResponseOutputText object { annotations, logprobs, text, type }` + The type of tool being defined: `file_search` - A text output from the model. + - `"file_search"` - - `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 }` + - `file_search: optional object { max_num_results, ranking_options }` - The annotations of the text output. + Overrides for the file search tool. - - `FileCitation object { file_id, filename, index, type }` + - `max_num_results: optional number` - A citation to a file. + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `file_id: string` + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - The ID of the file. + - `ranking_options: optional object { score_threshold, ranker }` - - `filename: string` + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - The filename of the file cited. + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `index: number` + - `score_threshold: number` - The index of the file in the list of files. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `type: "file_citation"` + - `ranker: optional "auto" or "default_2024_08_21"` - The type of the file citation. Always `file_citation`. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `"file_citation"` + - `"auto"` - - `URLCitation object { end_index, start_index, title, 2 more }` + - `"default_2024_08_21"` - A citation for a web resource used to generate a model response. + - `FunctionTool object { function, type }` - - `end_index: number` + - `function: FunctionDefinition` - The index of the last character of the URL citation in the message. + - `name: string` - - `start_index: number` + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - The index of the first character of the URL citation in the message. + - `description: optional string` - - `title: string` + A description of what the function does, used by the model to choose when and how to call the function. - The title of the web resource. + - `parameters: optional FunctionParameters` - - `type: "url_citation"` + The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - The type of the URL citation. Always `url_citation`. + Omitting `parameters` defines a function with an empty parameter list. - - `"url_citation"` + - `strict: optional boolean` - - `url: string` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-calling). - The URL of the web resource. + - `type: "function"` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + The type of tool being defined: `function` - A citation for a container file used to generate a model response. + - `"function"` - - `container_id: string` +- `top_p: optional number` - The ID of the container file. + 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. - - `end_index: number` + We generally recommend altering this or temperature but not both. - The index of the last character of the container file citation in the message. +### Returns - - `file_id: string` +- `Assistant object { id, created_at, description, 10 more }` - The ID of the file. + Represents an `assistant` that can call the model and use tools. - - `filename: string` + - `id: string` - The filename of the container file cited. + The identifier, which can be referenced in API endpoints. - - `start_index: number` + - `created_at: number` - The index of the first character of the container file citation in the message. + The Unix timestamp (in seconds) for when the assistant was created. - - `type: "container_file_citation"` + - `description: string` - The type of the container file citation. Always `container_file_citation`. + The description of the assistant. The maximum length is 512 characters. - - `"container_file_citation"` + - `instructions: string` - - `FilePath object { file_id, index, type }` + The system instructions that the assistant uses. The maximum length is 256,000 characters. - A path to a file. + - `metadata: Metadata` - - `file_id: string` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - The ID of the file. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `index: number` + - `model: string` - The index of the file in the list of files. + ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](/docs/models) for descriptions of them. - - `type: "file_path"` + - `name: string` - The type of the file path. Always `file_path`. + The name of the assistant. The maximum length is 256 characters. - - `"file_path"` + - `object: "assistant"` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + The object type, which is always `assistant`. - - `token: string` + - `"assistant"` - - `bytes: array of number` + - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` - - `logprob: number` + A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. - - `top_logprobs: array of object { token, bytes, logprob }` + - `CodeInterpreterTool object { type }` - - `token: string` + - `type: "code_interpreter"` - - `bytes: array of number` + The type of tool being defined: `code_interpreter` - - `logprob: number` + - `"code_interpreter"` - - `text: string` + - `FileSearchTool object { type, file_search }` - The text output from the model. + - `type: "file_search"` - - `type: "output_text"` + The type of tool being defined: `file_search` - The type of the output text. Always `output_text`. + - `"file_search"` - - `"output_text"` + - `file_search: optional object { max_num_results, ranking_options }` - - `BetaResponseOutputRefusal object { refusal, type }` + Overrides for the file search tool. - A refusal from the model. + - `max_num_results: optional number` - - `refusal: string` + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - The refusal explanation from the model. + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `type: "refusal"` + - `ranking_options: optional object { score_threshold, ranker }` - The type of the refusal. Always `refusal`. + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - `"refusal"` + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `role: "assistant"` + - `score_threshold: number` - The role of the output message. Always `assistant`. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `"assistant"` + - `ranker: optional "auto" or "default_2024_08_21"` - - `status: "in_progress" or "completed" or "incomplete"` + The ranker to use for the file search. If not specified will use the `auto` ranker. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `"auto"` - - `"in_progress"` + - `"default_2024_08_21"` - - `"completed"` + - `FunctionTool object { function, type }` - - `"incomplete"` + - `function: FunctionDefinition` - - `type: "message"` + - `name: string` - The type of the output message. Always `message`. + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `"message"` + - `description: optional string` - - `agent: optional object { agent_name }` + A description of what the function does, used by the model to choose when and how to call the function. - The agent that produced this item. + - `parameters: optional FunctionParameters` - - `agent_name: string` + The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - The canonical name of the agent that produced this item. + Omitting `parameters` defines a function with an empty parameter list. - - `phase: optional "commentary" or "final_answer"` + - `strict: optional boolean` - 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 enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-calling). - - `"commentary"` + - `type: "function"` - - `"final_answer"` + The type of tool being defined: `function` - - `FileSearchCall object { id, queries, status, 3 more }` + - `"function"` - The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + - `response_format: optional AssistantResponseFormatOption` - - `id: string` + Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - The unique ID of the file search tool call. + Setting to `{ "type": "json_schema", "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). - - `queries: array of string` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - The queries used to search for files. + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `"auto"` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + `auto` is the default value - - `"in_progress"` + - `"auto"` - - `"searching"` + - `ResponseFormatText object { type }` - - `"completed"` + Default response format. Used to generate text responses. - - `"incomplete"` + - `type: "text"` - - `"failed"` + The type of response format being defined. Always `text`. - - `type: "file_search_call"` + - `"text"` - The type of the file search tool call. Always `file_search_call`. + - `ResponseFormatJSONObject object { type }` - - `"file_search_call"` + 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. - - `agent: optional object { agent_name }` + - `type: "json_object"` - The agent that produced this item. + The type of response format being defined. Always `json_object`. - - `agent_name: string` + - `"json_object"` - The canonical name of the agent that produced this item. + - `ResponseFormatJSONSchema object { json_schema, type }` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - The results of the file search tool call. + - `json_schema: object { name, description, schema, strict }` - - `attributes: optional map[string or number or boolean]` + Structured Outputs configuration options, including a JSON Schema. - 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. + - `name: string` - - `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. - - `number` + - `description: optional string` - - `boolean` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `file_id: optional string` + - `schema: optional map[unknown]` - The unique ID of the file. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `filename: optional string` + - `strict: optional boolean` - The name of the file. + 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). - - `score: optional number` + - `type: "json_schema"` - The relevance score of the file - a value between 0 and 1. + The type of response format being defined. Always `json_schema`. - - `text: optional string` + - `"json_schema"` - The text that was retrieved from the file. + - `temperature: optional number` - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + 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. - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + - `tool_resources: optional object { code_interpreter, file_search }` - - `id: string` + A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - The unique ID of the computer call. + - `code_interpreter: optional object { file_ids }` - - `call_id: string` + - `file_ids: optional array of string` - An identifier used when responding to the tool call with output. + A list of [file](/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. - - `pending_safety_checks: array of object { id, code, message }` + - `file_search: optional object { vector_store_ids }` - The pending safety checks for the computer call. + - `vector_store_ids: optional array of string` - - `id: string` + The ID of the [vector store](/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. - The ID of the pending safety check. + - `top_p: optional number` - - `code: optional string` + 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 type of the pending safety check. + We generally recommend altering this or temperature but not both. - - `message: optional string` +### Example - Details about the pending safety check. +```http +curl https://api.openai.com/v1/assistants \ + -H 'Content-Type: application/json' \ + -H 'OpenAI-Beta: assistants=v2' \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-4o", + "temperature": 1, + "top_p": 1 + }' +``` - - `status: "in_progress" or "completed" or "incomplete"` +#### Response - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. +```json +{ + "id": "id", + "created_at": 0, + "description": "description", + "instructions": "instructions", + "metadata": { + "foo": "string" + }, + "model": "model", + "name": "name", + "object": "assistant", + "tools": [ + { + "type": "code_interpreter" + } + ], + "response_format": "auto", + "temperature": 1, + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "string" + ] + }, + "file_search": { + "vector_store_ids": [ + "string" + ] + } + }, + "top_p": 1 +} +``` - - `"in_progress"` +### Code Interpreter - - `"completed"` +```http +curl "https://api.openai.com/v1/assistants" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.", + "name": "Math Tutor", + "tools": [{"type": "code_interpreter"}], + "model": "gpt-4o" + }' +``` - - `"incomplete"` +#### Response - - `type: "computer_call"` +```json +{ + "id": "asst_abc123", + "object": "assistant", + "created_at": 1698984975, + "name": "Math Tutor", + "description": null, + "model": "gpt-4o", + "instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.", + "tools": [ + { + "type": "code_interpreter" + } + ], + "metadata": {}, + "top_p": 1.0, + "temperature": 1.0, + "response_format": "auto" +} +``` - The type of the computer call. Always `computer_call`. +### Files - - `"computer_call"` +```http +curl https://api.openai.com/v1/assistants \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies.", + "tools": [{"type": "file_search"}], + "tool_resources": {"file_search": {"vector_store_ids": ["vs_123"]}}, + "model": "gpt-4o" + }' +``` - - `action: optional BetaComputerAction` +#### Response - A click action. +```json +{ + "id": "asst_abc123", + "object": "assistant", + "created_at": 1699009403, + "name": "HR Helper", + "description": null, + "model": "gpt-4o", + "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies.", + "tools": [ + { + "type": "file_search" + } + ], + "tool_resources": { + "file_search": { + "vector_store_ids": ["vs_123"] + } + }, + "metadata": {}, + "top_p": 1.0, + "temperature": 1.0, + "response_format": "auto" +} +``` - - `Click object { button, type, x, 2 more }` +## Delete assistant - A click action. +**delete** `/assistants/{assistant_id}` - - `button: "left" or "right" or "wheel" or 2 more` +Delete an assistant. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. +### Path Parameters - - `"left"` +- `assistant_id: string` - - `"right"` +### Returns - - `"wheel"` +- `AssistantDeleted object { id, deleted, object }` - - `"back"` + - `id: string` - - `"forward"` + - `deleted: boolean` - - `type: "click"` + - `object: "assistant.deleted"` - Specifies the event type. For a click action, this property is always `click`. + - `"assistant.deleted"` - - `"click"` +### Example - - `x: number` +```http +curl https://api.openai.com/v1/assistants/$ASSISTANT_ID \ + -X DELETE \ + -H 'OpenAI-Beta: assistants=v2' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - The x-coordinate where the click occurred. +#### Response - - `y: number` +```json +{ + "id": "id", + "deleted": true, + "object": "assistant.deleted" +} +``` - The y-coordinate where the click occurred. +### Example - - `keys: optional array of string` +```http +curl https://api.openai.com/v1/assistants/asst_abc123 \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" \ + -X DELETE +``` - The keys being held while clicking. +#### Response - - `DoubleClick object { keys, type, x, y }` +```json +{ + "id": "asst_abc123", + "object": "assistant.deleted", + "deleted": true +} +``` - A double click action. +## List assistants - - `keys: array of string` +**get** `/assistants` - The keys being held while double-clicking. +Returns a list of assistants. - - `type: "double_click"` +### Query Parameters - Specifies the event type. For a double click action, this property is always set to `double_click`. +- `after: optional string` - - `"double_click"` + A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. - - `x: number` +- `before: optional string` - The x-coordinate where the double click occurred. + A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. - - `y: number` +- `limit: optional number` - The y-coordinate where the double click occurred. + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - - `Drag object { path, type, keys }` +- `order: optional "asc" or "desc"` - A drag action. + Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. - - `path: array of object { x, y }` + - `"asc"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `"desc"` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` +### Returns - - `x: number` +- `data: array of Assistant` - The x-coordinate. + - `id: string` - - `y: number` + The identifier, which can be referenced in API endpoints. - The y-coordinate. + - `created_at: number` - - `type: "drag"` + The Unix timestamp (in seconds) for when the assistant was created. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `description: string` - - `"drag"` + The description of the assistant. The maximum length is 512 characters. - - `keys: optional array of string` + - `instructions: string` - The keys being held while dragging the mouse. + The system instructions that the assistant uses. The maximum length is 256,000 characters. - - `Keypress object { keys, type }` + - `metadata: Metadata` - A collection of keypresses the model would like to perform. + 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: array of string` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `model: string` - - `type: "keypress"` + ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](/docs/models) for descriptions of them. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `name: string` - - `"keypress"` + The name of the assistant. The maximum length is 256 characters. - - `Move object { type, x, y, keys }` + - `object: "assistant"` - A mouse move action. + The object type, which is always `assistant`. - - `type: "move"` + - `"assistant"` - Specifies the event type. For a move action, this property is always set to `move`. + - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` - - `"move"` + A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. - - `x: number` + - `CodeInterpreterTool object { type }` - The x-coordinate to move to. + - `type: "code_interpreter"` - - `y: number` + The type of tool being defined: `code_interpreter` - The y-coordinate to move to. + - `"code_interpreter"` - - `keys: optional array of string` + - `FileSearchTool object { type, file_search }` - The keys being held while moving the mouse. + - `type: "file_search"` - - `Screenshot object { type }` + The type of tool being defined: `file_search` - A screenshot action. + - `"file_search"` - - `type: "screenshot"` + - `file_search: optional object { max_num_results, ranking_options }` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + Overrides for the file search tool. - - `"screenshot"` + - `max_num_results: optional number` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - A scroll action. + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `scroll_x: number` + - `ranking_options: optional object { score_threshold, ranker }` - The horizontal scroll distance. + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - `scroll_y: number` + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - The vertical scroll distance. + - `score_threshold: number` - - `type: "scroll"` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `ranker: optional "auto" or "default_2024_08_21"` - - `"scroll"` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `x: number` + - `"auto"` - The x-coordinate where the scroll occurred. + - `"default_2024_08_21"` - - `y: number` + - `FunctionTool object { function, type }` - The y-coordinate where the scroll occurred. + - `function: FunctionDefinition` - - `keys: optional array of string` + - `name: string` - The keys being held while scrolling. + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `Type object { text, type }` + - `description: optional string` - An action to type in text. + A description of what the function does, used by the model to choose when and how to call the function. - - `text: string` + - `parameters: optional FunctionParameters` - The text to type. + The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - `type: "type"` + Omitting `parameters` defines a function with an empty parameter list. - Specifies the event type. For a type action, this property is always set to `type`. + - `strict: optional boolean` - - `"type"` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-calling). - - `Wait object { type }` + - `type: "function"` - A wait action. + The type of tool being defined: `function` - - `type: "wait"` + - `"function"` - Specifies the event type. For a wait action, this property is always set to `wait`. + - `response_format: optional AssistantResponseFormatOption` - - `"wait"` + Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `actions: optional BetaComputerActionList` + Setting to `{ "type": "json_schema", "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). - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `Click object { button, type, x, 2 more }` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - A click action. + - `"auto"` - - `DoubleClick object { keys, type, x, y }` + `auto` is the default value - A double click action. + - `"auto"` - - `Drag object { path, type, keys }` + - `ResponseFormatText object { type }` - A drag action. + Default response format. Used to generate text responses. - - `Keypress object { keys, type }` + - `type: "text"` - A collection of keypresses the model would like to perform. + The type of response format being defined. Always `text`. - - `Move object { type, x, y, keys }` + - `"text"` - A mouse move action. + - `ResponseFormatJSONObject object { type }` - - `Screenshot 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. - A screenshot action. + - `type: "json_object"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + The type of response format being defined. Always `json_object`. - A scroll action. + - `"json_object"` - - `Type object { text, type }` + - `ResponseFormatJSONSchema object { json_schema, type }` - An action to type in text. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `Wait object { type }` + - `json_schema: object { name, description, schema, strict }` - A wait action. + Structured Outputs configuration options, including a JSON Schema. - - `agent: optional object { agent_name }` + - `name: string` - The agent that produced this item. + 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. - - `agent_name: string` + - `description: optional string` - The canonical name of the agent that produced this item. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `ComputerCallOutput object { call_id, output, type, 4 more }` + - `schema: optional map[unknown]` - The output of a computer tool call. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `call_id: string` + - `strict: optional boolean` - The ID of the computer tool call that produced the output. + 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). - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `type: "json_schema"` - A computer screenshot image used with the computer use tool. + The type of response format being defined. Always `json_schema`. - - `type: "computer_screenshot"` + - `"json_schema"` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `temperature: optional number` - - `"computer_screenshot"` + 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. - - `file_id: optional string` + - `tool_resources: optional object { code_interpreter, file_search }` - The identifier of an uploaded file that contains the screenshot. + A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - - `image_url: optional string` + - `code_interpreter: optional object { file_ids }` - The URL of the screenshot image. + - `file_ids: optional array of string` - - `type: "computer_call_output"` + A list of [file](/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. - The type of the computer tool call output. Always `computer_call_output`. + - `file_search: optional object { vector_store_ids }` - - `"computer_call_output"` + - `vector_store_ids: optional array of string` - - `id: optional string` + The ID of the [vector store](/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. - The ID of the computer tool call output. + - `top_p: optional number` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + 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 safety checks reported by the API that have been acknowledged by the developer. + We generally recommend altering this or temperature but not both. - - `id: string` +- `first_id: string` - The ID of the pending safety check. +- `has_more: boolean` - - `code: optional string` +- `last_id: string` - The type of the pending safety check. +- `object: string` - - `message: optional string` +### Example - Details about the pending safety check. +```http +curl https://api.openai.com/v1/assistants \ + -H 'OpenAI-Beta: assistants=v2' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `agent: optional object { agent_name }` +#### Response - The agent that produced this item. +```json +{ + "data": [ + { + "id": "id", + "created_at": 0, + "description": "description", + "instructions": "instructions", + "metadata": { + "foo": "string" + }, + "model": "model", + "name": "name", + "object": "assistant", + "tools": [ + { + "type": "code_interpreter" + } + ], + "response_format": "auto", + "temperature": 1, + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "string" + ] + }, + "file_search": { + "vector_store_ids": [ + "string" + ] + } + }, + "top_p": 1 + } + ], + "first_id": "asst_abc123", + "has_more": false, + "last_id": "asst_abc456", + "object": "list" +} +``` - - `agent_name: string` +### Example - The canonical name of the agent that produced this item. +```http +curl "https://api.openai.com/v1/assistants?order=desc&limit=20" \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" +``` - - `status: optional "in_progress" or "completed" or "incomplete"` +#### Response - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. +```json +{ + "object": "list", + "data": [ + { + "id": "asst_abc123", + "object": "assistant", + "created_at": 1698982736, + "name": "Coding Tutor", + "description": null, + "model": "gpt-4o", + "instructions": "You are a helpful assistant designed to make me better at coding!", + "tools": [], + "tool_resources": {}, + "metadata": {}, + "top_p": 1.0, + "temperature": 1.0, + "response_format": "auto" + }, + { + "id": "asst_abc456", + "object": "assistant", + "created_at": 1698982718, + "name": "My Assistant", + "description": null, + "model": "gpt-4o", + "instructions": "You are a helpful assistant designed to make me better at coding!", + "tools": [], + "tool_resources": {}, + "metadata": {}, + "top_p": 1.0, + "temperature": 1.0, + "response_format": "auto" + }, + { + "id": "asst_abc789", + "object": "assistant", + "created_at": 1698982643, + "name": null, + "description": null, + "model": "gpt-4o", + "instructions": null, + "tools": [], + "tool_resources": {}, + "metadata": {}, + "top_p": 1.0, + "temperature": 1.0, + "response_format": "auto" + } + ], + "first_id": "asst_abc123", + "last_id": "asst_abc789", + "has_more": false +} +``` - - `"in_progress"` +## Retrieve assistant - - `"completed"` +**get** `/assistants/{assistant_id}` - - `"incomplete"` +Retrieves an assistant. - - `WebSearchCall object { id, action, status, 2 more }` +### Path Parameters - The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. +- `assistant_id: string` - - `id: string` +### Returns - The unique ID of the web search tool call. +- `Assistant object { id, created_at, description, 10 more }` - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + Represents an `assistant` that can call the model and use tools. - 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). + - `id: string` - - `Search object { type, queries, query, sources }` + The identifier, which can be referenced in API endpoints. - Action type "search" - Performs a web search query. + - `created_at: number` - - `type: "search"` + The Unix timestamp (in seconds) for when the assistant was created. - The action type. + - `description: string` - - `"search"` + The description of the assistant. The maximum length is 512 characters. - - `queries: optional array of string` + - `instructions: string` - The search queries. + The system instructions that the assistant uses. The maximum length is 256,000 characters. - - `query: optional string` + - `metadata: Metadata` - The search query. + 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. - - `sources: optional array of object { type, url }` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The sources used in the search. + - `model: string` - - `type: "url"` + ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](/docs/models) for descriptions of them. - The type of source. Always `url`. + - `name: string` - - `"url"` + The name of the assistant. The maximum length is 256 characters. - - `url: string` + - `object: "assistant"` - The URL of the source. + The object type, which is always `assistant`. - - `OpenPage object { type, url }` + - `"assistant"` - Action type "open_page" - Opens a specific URL from search results. + - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` - - `type: "open_page"` + A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. - The action type. + - `CodeInterpreterTool object { type }` - - `"open_page"` + - `type: "code_interpreter"` - - `url: optional string` + The type of tool being defined: `code_interpreter` - The URL opened by the model. + - `"code_interpreter"` - - `FindInPage object { pattern, type, url }` + - `FileSearchTool object { type, file_search }` - Action type "find_in_page": Searches for a pattern within a loaded page. + - `type: "file_search"` - - `pattern: string` + The type of tool being defined: `file_search` - The pattern or text to search for within the page. + - `"file_search"` - - `type: "find_in_page"` + - `file_search: optional object { max_num_results, ranking_options }` - The action type. + Overrides for the file search tool. - - `"find_in_page"` + - `max_num_results: optional number` - - `url: string` + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - The URL of the page searched for the pattern. + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `ranking_options: optional object { score_threshold, ranker }` - The status of the web search tool call. + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - `"in_progress"` + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `"searching"` + - `score_threshold: number` - - `"completed"` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `"failed"` + - `ranker: optional "auto" or "default_2024_08_21"` - - `type: "web_search_call"` + The ranker to use for the file search. If not specified will use the `auto` ranker. - The type of the web search tool call. Always `web_search_call`. + - `"auto"` - - `"web_search_call"` + - `"default_2024_08_21"` - - `agent: optional object { agent_name }` + - `FunctionTool object { function, type }` - The agent that produced this item. + - `function: FunctionDefinition` - - `agent_name: string` + - `name: string` - The canonical name of the agent that produced this item. + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `FunctionCall object { arguments, call_id, name, 6 more }` + - `description: optional string` - A tool call to run a function. See the - [function calling guide](/docs/guides/function-calling) for more information. + A description of what the function does, used by the model to choose when and how to call the function. - - `arguments: string` + - `parameters: optional FunctionParameters` - A JSON string of the arguments to pass to the function. + The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - `call_id: string` + Omitting `parameters` defines a function with an empty parameter list. - The unique ID of the function tool call generated by the model. + - `strict: optional boolean` - - `name: string` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-calling). - The name of the function to run. + - `type: "function"` - - `type: "function_call"` + The type of tool being defined: `function` - The type of the function tool call. Always `function_call`. + - `"function"` - - `"function_call"` + - `response_format: optional AssistantResponseFormatOption` - - `id: optional string` + Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - The unique ID of the function tool call. + Setting to `{ "type": "json_schema", "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). - - `agent: optional object { agent_name }` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - The agent that produced this item. + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `agent_name: string` + - `"auto"` - The canonical name of the agent that produced this item. + `auto` is the default value - - `caller: optional object { type } or object { caller_id, type }` + - `"auto"` - The execution context that produced this tool call. + - `ResponseFormatText object { type }` - - `Direct object { type }` + Default response format. Used to generate text responses. - - `type: "direct"` + - `type: "text"` - - `"direct"` + The type of response format being defined. Always `text`. - - `Program object { caller_id, type }` + - `"text"` - - `caller_id: string` + - `ResponseFormatJSONObject object { type }` - The call ID of the program item that produced this tool call. + 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: "program"` + - `type: "json_object"` - - `"program"` + The type of response format being defined. Always `json_object`. - - `namespace: optional string` + - `"json_object"` - The namespace of the function to run. + - `ResponseFormatJSONSchema object { json_schema, type }` - - `status: optional "in_progress" or "completed" or "incomplete"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `json_schema: object { name, description, schema, strict }` - - `"in_progress"` + Structured Outputs configuration options, including a JSON Schema. - - `"completed"` + - `name: string` - - `"incomplete"` + 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. - - `FunctionCallOutput object { call_id, output, type, 4 more }` + - `description: optional string` - The output of a function tool call. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `call_id: string` + - `schema: optional map[unknown]` - The unique ID of the function tool call generated by the model. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` + - `strict: optional boolean` - Text, image, or file output of the function tool call. + 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). - - `string` + - `type: "json_schema"` - A JSON string of the output of the function tool call. + The type of response format being defined. Always `json_schema`. - - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` + - `"json_schema"` - An array of content outputs (text, image, file) for the function tool call. + - `temperature: optional number` - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + 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. - A text input to the model. + - `tool_resources: optional object { code_interpreter, file_search }` - - `text: string` + A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - The text input to the model. + - `code_interpreter: optional object { file_ids }` - - `type: "input_text"` + - `file_ids: optional array of string` - The type of the input item. Always `input_text`. + A list of [file](/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. - - `"input_text"` + - `file_search: optional object { vector_store_ids }` - - `prompt_cache_breakpoint: optional object { mode }` + - `vector_store_ids: optional array of 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 ID of the [vector store](/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. - - `mode: "explicit"` + - `top_p: optional number` - The breakpoint mode. Always `explicit`. + 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. - - `"explicit"` + We generally recommend altering this or temperature but not both. - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` +### Example - An image input to the model. Learn about [image inputs](/docs/guides/vision) +```http +curl https://api.openai.com/v1/assistants/$ASSISTANT_ID \ + -H 'OpenAI-Beta: assistants=v2' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `type: "input_image"` +#### Response - The type of the input item. Always `input_image`. +```json +{ + "id": "id", + "created_at": 0, + "description": "description", + "instructions": "instructions", + "metadata": { + "foo": "string" + }, + "model": "model", + "name": "name", + "object": "assistant", + "tools": [ + { + "type": "code_interpreter" + } + ], + "response_format": "auto", + "temperature": 1, + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "string" + ] + }, + "file_search": { + "vector_store_ids": [ + "string" + ] + } + }, + "top_p": 1 +} +``` - - `"input_image"` +### Example - - `detail: optional "low" or "high" or "auto" or "original"` +```http +curl https://api.openai.com/v1/assistants/asst_abc123 \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" +``` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. +#### Response - - `"low"` +```json +{ + "id": "asst_abc123", + "object": "assistant", + "created_at": 1699009709, + "name": "HR Helper", + "description": null, + "model": "gpt-4o", + "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies.", + "tools": [ + { + "type": "file_search" + } + ], + "metadata": {}, + "top_p": 1.0, + "temperature": 1.0, + "response_format": "auto" +} +``` - - `"high"` +## Modify assistant - - `"auto"` +**post** `/assistants/{assistant_id}` - - `"original"` +Modifies an assistant. - - `file_id: optional string` +### Path Parameters - The ID of the file to be sent to the model. +- `assistant_id: string` - - `image_url: optional string` +### Body Parameters - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. +- `description: optional string` - - `prompt_cache_breakpoint: optional object { mode }` + The description of the assistant. The maximum length is 512 characters. - 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. +- `instructions: optional string` - - `mode: "explicit"` + The system instructions that the assistant uses. The maximum length is 256,000 characters. - The breakpoint mode. Always `explicit`. +- `metadata: optional Metadata` - - `"explicit"` + 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. - - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - A file input to the model. +- `model: optional string or "gpt-5" or "gpt-5-mini" or "gpt-5-nano" or 39 more` - - `type: "input_file"` + ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](/docs/models) for descriptions of them. - The type of the input item. Always `input_file`. + - `string` - - `"input_file"` + - `AssistantSupportedModels = "gpt-5" or "gpt-5-mini" or "gpt-5-nano" or 39 more` - - `detail: optional "auto" or "low" or "high"` + ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](/docs/models) for descriptions of them. - 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`. + - `"gpt-5"` - - `"auto"` + - `"gpt-5-mini"` - - `"low"` + - `"gpt-5-nano"` - - `"high"` + - `"gpt-5-2025-08-07"` - - `file_data: optional string` + - `"gpt-5-mini-2025-08-07"` - The base64-encoded data of the file to be sent to the model. + - `"gpt-5-nano-2025-08-07"` - - `file_id: optional string` + - `"gpt-4.1"` - The ID of the file to be sent to the model. + - `"gpt-4.1-mini"` - - `file_url: optional string` + - `"gpt-4.1-nano"` - The URL of the file to be sent to the model. + - `"gpt-4.1-2025-04-14"` - - `filename: optional string` + - `"gpt-4.1-mini-2025-04-14"` - The name of the file to be sent to the model. + - `"gpt-4.1-nano-2025-04-14"` - - `prompt_cache_breakpoint: optional object { mode }` + - `"o3-mini"` - 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. + - `"o3-mini-2025-01-31"` - - `mode: "explicit"` + - `"o1"` - The breakpoint mode. Always `explicit`. + - `"o1-2024-12-17"` - - `"explicit"` + - `"gpt-4o"` - - `type: "function_call_output"` + - `"gpt-4o-2024-11-20"` - The type of the function tool call output. Always `function_call_output`. + - `"gpt-4o-2024-08-06"` - - `"function_call_output"` + - `"gpt-4o-2024-05-13"` - - `id: optional string` + - `"gpt-4o-mini"` - The unique ID of the function tool call output. Populated when this item is returned via API. + - `"gpt-4o-mini-2024-07-18"` - - `agent: optional object { agent_name }` + - `"gpt-4.5-preview"` - The agent that produced this item. + - `"gpt-4.5-preview-2025-02-27"` - - `agent_name: string` + - `"gpt-4-turbo"` - The canonical name of the agent that produced this item. + - `"gpt-4-turbo-2024-04-09"` - - `caller: optional object { type } or object { caller_id, type }` + - `"gpt-4-0125-preview"` - The execution context that produced this tool call. + - `"gpt-4-turbo-preview"` - - `Direct object { type }` + - `"gpt-4-1106-preview"` - - `type: "direct"` + - `"gpt-4-vision-preview"` - The caller type. Always `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"` - The caller type. Always `program`. + - `"gpt-3.5-turbo"` - - `"program"` + - `"gpt-3.5-turbo-16k"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"gpt-3.5-turbo-0613"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `"gpt-3.5-turbo-1106"` - - `"in_progress"` + - `"gpt-3.5-turbo-0125"` - - `"completed"` + - `"gpt-3.5-turbo-16k-0613"` - - `"incomplete"` +- `name: optional string` - - `AgentMessage object { author, content, recipient, 3 more }` + The name of the assistant. The maximum length is 256 characters. - A message routed between agents. +- `reasoning_effort: optional ReasoningEffort` - - `author: 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 sending agent identity. + - `"none"` - - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` + - `"minimal"` - Plaintext, image, or encrypted content sent between agents. + - `"low"` - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + - `"medium"` - A text input to the model. + - `"high"` - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + - `"xhigh"` - An image input to the model. Learn about [image inputs](/docs/guides/vision) + - `"max"` - - `EncryptedContent object { encrypted_content, type }` +- `response_format: optional AssistantResponseFormatOption` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `encrypted_content: string` + Setting to `{ "type": "json_schema", "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). - Opaque encrypted content. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `type: "encrypted_content"` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - The type of the input item. Always `encrypted_content`. + - `"auto"` - - `"encrypted_content"` + `auto` is the default value - - `recipient: string` + - `"auto"` - The destination agent identity. + - `ResponseFormatText object { type }` - - `type: "agent_message"` + Default response format. Used to generate text responses. - The item type. Always `agent_message`. + - `type: "text"` - - `"agent_message"` + The type of response format being defined. Always `text`. - - `id: optional string` + - `"text"` - The unique ID of this agent message item. + - `ResponseFormatJSONObject object { type }` - - `agent: optional object { agent_name }` + 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 agent that produced this item. + - `type: "json_object"` - - `agent_name: string` + The type of response format being defined. Always `json_object`. - The canonical name of the agent that produced this item. + - `"json_object"` - - `MultiAgentCall object { action, arguments, call_id, 3 more }` + - `ResponseFormatJSONSchema object { json_schema, type }` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - The multi-agent action that was executed. + - `json_schema: object { name, description, schema, strict }` - - `"spawn_agent"` + Structured Outputs configuration options, including a JSON Schema. - - `"interrupt_agent"` + - `name: string` - - `"list_agents"` + 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. - - `"send_message"` + - `description: optional string` - - `"followup_task"` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `"wait_agent"` + - `schema: optional map[unknown]` - - `arguments: string` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - The action arguments as a JSON string. + - `strict: optional boolean` - - `call_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 unique ID linking this call to its output. + - `type: "json_schema"` - - `type: "multi_agent_call"` + The type of response format being defined. Always `json_schema`. - The item type. Always `multi_agent_call`. + - `"json_schema"` - - `"multi_agent_call"` +- `temperature: optional number` - - `id: optional 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. - The unique ID of this multi-agent call. +- `tool_resources: optional object { code_interpreter, file_search }` - - `agent: optional object { agent_name }` + A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - The agent that produced this item. + - `code_interpreter: optional object { file_ids }` - - `agent_name: string` + - `file_ids: optional array of string` - The canonical name of the agent that produced this item. + Overrides the list of [file](/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. - - `MultiAgentCallOutput object { action, call_id, output, 3 more }` + - `file_search: optional object { vector_store_ids }` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `vector_store_ids: optional array of string` - The multi-agent action that produced this result. + Overrides the [vector store](/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. - - `"spawn_agent"` +- `tools: optional array of CodeInterpreterTool or FileSearchTool or FunctionTool` - - `"interrupt_agent"` + A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. - - `"list_agents"` + - `CodeInterpreterTool object { type }` - - `"send_message"` + - `type: "code_interpreter"` - - `"followup_task"` + The type of tool being defined: `code_interpreter` - - `"wait_agent"` + - `"code_interpreter"` - - `call_id: string` + - `FileSearchTool object { type, file_search }` - The unique ID of the multi-agent call. + - `type: "file_search"` - - `output: array of object { text, type, annotations }` + The type of tool being defined: `file_search` - Text output returned by the multi-agent action. + - `"file_search"` - - `text: string` + - `file_search: optional object { max_num_results, ranking_options }` - The text content. + Overrides for the file search tool. - - `type: "output_text"` + - `max_num_results: optional number` - The content type. Always `output_text`. + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `"output_text"` + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `annotations: optional 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 }` + - `ranking_options: optional object { score_threshold, ranker }` - Citations associated with the text content. + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - `FileCitation object { file_id, filename, index, type }` + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `file_id: string` + - `score_threshold: number` - The ID of the file. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `filename: string` + - `ranker: optional "auto" or "default_2024_08_21"` - The filename of the file cited. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `index: number` + - `"auto"` - The index of the file in the list of files. + - `"default_2024_08_21"` - - `type: "file_citation"` + - `FunctionTool object { function, type }` - The citation type. Always `file_citation`. + - `function: FunctionDefinition` - - `"file_citation"` + - `name: string` - - `URLCitation object { end_index, start_index, title, 2 more }` + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `end_index: number` + - `description: optional string` - The index of the last character of the citation in the message. + A description of what the function does, used by the model to choose when and how to call the function. - - `start_index: number` + - `parameters: optional FunctionParameters` - The index of the first character of the citation in the message. + The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - `title: string` + Omitting `parameters` defines a function with an empty parameter list. - The title of the cited resource. + - `strict: optional boolean` - - `type: "url_citation"` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-calling). - The citation type. Always `url_citation`. + - `type: "function"` - - `"url_citation"` + The type of tool being defined: `function` - - `url: string` + - `"function"` - The URL of the cited resource. +- `top_p: optional number` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + 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. - - `container_id: string` + We generally recommend altering this or temperature but not both. - The ID of the container. +### Returns - - `end_index: number` +- `Assistant object { id, created_at, description, 10 more }` - The index of the last character of the citation in the message. + Represents an `assistant` that can call the model and use tools. - - `file_id: string` + - `id: string` - The ID of the container file. + The identifier, which can be referenced in API endpoints. - - `filename: string` + - `created_at: number` - The filename of the container file cited. + The Unix timestamp (in seconds) for when the assistant was created. - - `start_index: number` + - `description: string` - The index of the first character of the citation in the message. + The description of the assistant. The maximum length is 512 characters. - - `type: "container_file_citation"` + - `instructions: string` - The citation type. Always `container_file_citation`. + The system instructions that the assistant uses. The maximum length is 256,000 characters. - - `"container_file_citation"` + - `metadata: Metadata` - - `type: "multi_agent_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. - The item type. Always `multi_agent_call_output`. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"multi_agent_call_output"` + - `model: string` - - `id: optional string` + ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](/docs/models) for descriptions of them. - The unique ID of this multi-agent call output. + - `name: string` - - `agent: optional object { agent_name }` + The name of the assistant. The maximum length is 256 characters. - The agent that produced this item. + - `object: "assistant"` - - `agent_name: string` + The object type, which is always `assistant`. - The canonical name of the agent that produced this item. + - `"assistant"` - - `ToolSearchCall object { arguments, type, id, 4 more }` + - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` - - `arguments: unknown` + A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. - The arguments supplied to the tool search call. + - `CodeInterpreterTool object { type }` - - `type: "tool_search_call"` + - `type: "code_interpreter"` - The item type. Always `tool_search_call`. + The type of tool being defined: `code_interpreter` - - `"tool_search_call"` + - `"code_interpreter"` - - `id: optional string` + - `FileSearchTool object { type, file_search }` - The unique ID of this tool search call. + - `type: "file_search"` - - `agent: optional object { agent_name }` + The type of tool being defined: `file_search` - The agent that produced this item. + - `"file_search"` - - `agent_name: string` + - `file_search: optional object { max_num_results, ranking_options }` - The canonical name of the agent that produced this item. + Overrides for the file search tool. - - `call_id: optional string` + - `max_num_results: optional number` - The unique ID of the tool search call generated by the model. + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `execution: optional "server" or "client"` + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - Whether tool search was executed by the server or by the client. + - `ranking_options: optional object { score_threshold, ranker }` - - `"server"` + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - `"client"` + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `score_threshold: number` - The status of the tool search call. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `"in_progress"` + - `ranker: optional "auto" or "default_2024_08_21"` - - `"completed"` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `"incomplete"` + - `"auto"` - - `ToolSearchOutput object { tools, type, id, 4 more }` + - `"default_2024_08_21"` - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + - `FunctionTool object { function, type }` - The loaded tool definitions returned by the tool search output. + - `function: FunctionDefinition` - - `Function object { name, parameters, strict, 5 more }` + - `name: 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 name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `name: string` + - `description: optional string` - The name of the function to call. + A description of what the function does, used by the model to choose when and how to call the function. - - `parameters: map[unknown]` + - `parameters: optional FunctionParameters` - A JSON schema object describing the parameters of the function. + The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - `strict: boolean` + Omitting `parameters` defines a function with an empty parameter list. - Whether strict parameter validation is enforced for this function tool. + - `strict: optional boolean` + + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-calling). - `type: "function"` - The type of the function tool. Always `function`. + The type of tool being defined: `function` - `"function"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `response_format: optional AssistantResponseFormatOption` - The tool invocation context(s). + Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `"direct"` + Setting to `{ "type": "json_schema", "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). - - `"programmatic"` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `defer_loading: optional boolean` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - Whether this function is deferred and loaded via tool search. + - `"auto"` - - `description: optional string` + `auto` is the default value - A description of the function. Used by the model to determine whether or not to call the function. + - `"auto"` - - `output_schema: optional map[unknown]` + - `ResponseFormatText object { type }` - A JSON schema object describing the JSON value encoded in string outputs for this function. + Default response format. Used to generate text responses. - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `type: "text"` - 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 response format being defined. Always `text`. - - `type: "file_search"` + - `"text"` - The type of the file search tool. Always `file_search`. + - `ResponseFormatJSONObject object { type }` - - `"file_search"` + 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. - - `vector_store_ids: array of string` + - `type: "json_object"` - The IDs of the vector stores to search. + The type of response format being defined. Always `json_object`. - - `filters: optional object { key, type, value } or object { filters, type }` + - `"json_object"` - A filter to apply. + - `ResponseFormatJSONSchema object { json_schema, type }` - - `ComparisonFilter object { key, type, value }` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `json_schema: object { name, description, schema, strict }` - - `key: string` + Structured Outputs configuration options, including a JSON Schema. - The key to compare against the value. + - `name: string` - - `type: "eq" or "ne" or "gt" or 5 more` + 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. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `description: optional string` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in - - - `"eq"` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `"ne"` + - `schema: optional map[unknown]` - - `"gt"` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `"gte"` + - `strict: optional boolean` - - `"lt"` + 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). - - `"lte"` + - `type: "json_schema"` - - `"in"` + The type of response format being defined. Always `json_schema`. - - `"nin"` + - `"json_schema"` - - `value: string or number or boolean or array of string or number` + - `temperature: optional number` - The value to compare against the attribute key; supports string, number, or boolean types. + 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. - - `string` + - `tool_resources: optional object { code_interpreter, file_search }` - - `number` + A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - - `boolean` + - `code_interpreter: optional object { file_ids }` - - `array of string or number` + - `file_ids: optional array of string` - - `string` + A list of [file](/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. - - `number` + - `file_search: optional object { vector_store_ids }` - - `CompoundFilter object { filters, type }` + - `vector_store_ids: optional array of string` - Combine multiple filters using `and` or `or`. + The ID of the [vector store](/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. - - `filters: array of object { key, type, value } or unknown` + - `top_p: optional number` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + 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. - - `ComparisonFilter object { key, type, value }` + We generally recommend altering this or temperature but not both. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. +### Example - - `key: string` +```http +curl https://api.openai.com/v1/assistants/$ASSISTANT_ID \ + -H 'Content-Type: application/json' \ + -H 'OpenAI-Beta: assistants=v2' \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "temperature": 1, + "top_p": 1 + }' +``` - The key to compare against the value. +#### Response - - `type: "eq" or "ne" or "gt" or 5 more` +```json +{ + "id": "id", + "created_at": 0, + "description": "description", + "instructions": "instructions", + "metadata": { + "foo": "string" + }, + "model": "model", + "name": "name", + "object": "assistant", + "tools": [ + { + "type": "code_interpreter" + } + ], + "response_format": "auto", + "temperature": 1, + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "string" + ] + }, + "file_search": { + "vector_store_ids": [ + "string" + ] + } + }, + "top_p": 1 +} +``` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. +### Example - - `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 +```http +curl https://api.openai.com/v1/assistants/asst_abc123 \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.", + "tools": [{"type": "file_search"}], + "model": "gpt-4o" + }' +``` - - `"eq"` +#### Response - - `"ne"` +```json +{ + "id": "asst_123", + "object": "assistant", + "created_at": 1699009709, + "name": "HR Helper", + "description": null, + "model": "gpt-4o", + "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.", + "tools": [ + { + "type": "file_search" + } + ], + "tool_resources": { + "file_search": { + "vector_store_ids": [] + } + }, + "metadata": {}, + "top_p": 1.0, + "temperature": 1.0, + "response_format": "auto" +} +``` - - `"gt"` +## Domain Types - - `"gte"` +### Assistant - - `"lt"` +- `Assistant object { id, created_at, description, 10 more }` - - `"lte"` + Represents an `assistant` that can call the model and use tools. - - `"in"` + - `id: string` - - `"nin"` + The identifier, which can be referenced in API endpoints. - - `value: string or number or boolean or array of string or number` + - `created_at: number` - The value to compare against the attribute key; supports string, number, or boolean types. + The Unix timestamp (in seconds) for when the assistant was created. - - `string` + - `description: string` - - `number` + The description of the assistant. The maximum length is 512 characters. - - `boolean` + - `instructions: string` - - `array of string or number` + The system instructions that the assistant uses. The maximum length is 256,000 characters. - - `string` + - `metadata: Metadata` - - `number` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `unknown` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `type: "and" or "or"` + - `model: string` - Type of operation: `and` or `or`. + ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](/docs/models) for descriptions of them. - - `"and"` + - `name: string` - - `"or"` + The name of the assistant. The maximum length is 256 characters. - - `max_num_results: optional number` + - `object: "assistant"` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + The object type, which is always `assistant`. - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `"assistant"` - Ranking options for search. + - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` - - `hybrid_search: optional object { embedding_weight, text_weight }` + A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `CodeInterpreterTool object { type }` - - `embedding_weight: number` + - `type: "code_interpreter"` - The weight of the embedding in the reciprocal ranking fusion. + The type of tool being defined: `code_interpreter` - - `text_weight: number` + - `"code_interpreter"` - The weight of the text in the reciprocal ranking fusion. + - `FileSearchTool object { type, file_search }` - - `ranker: optional "auto" or "default-2024-11-15"` + - `type: "file_search"` - The ranker to use for the file search. + The type of tool being defined: `file_search` - - `"auto"` + - `"file_search"` - - `"default-2024-11-15"` + - `file_search: optional object { max_num_results, ranking_options }` - - `score_threshold: optional number` + Overrides for the file search tool. - 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. + - `max_num_results: optional number` - - `Computer object { type }` + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `type: "computer"` + - `ranking_options: optional object { score_threshold, ranker }` - The type of the computer tool. Always `computer`. + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - `"computer"` + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `score_threshold: number` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `display_height: number` + - `ranker: optional "auto" or "default_2024_08_21"` - The height of the computer display. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `display_width: number` + - `"auto"` - The width of the computer display. + - `"default_2024_08_21"` - - `environment: "windows" or "mac" or "linux" or 2 more` + - `FunctionTool object { function, type }` - The type of computer environment to control. + - `function: FunctionDefinition` - - `"windows"` + - `name: string` - - `"mac"` + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `"linux"` + - `description: optional string` - - `"ubuntu"` + A description of what the function does, used by the model to choose when and how to call the function. - - `"browser"` + - `parameters: optional FunctionParameters` - - `type: "computer_use_preview"` + The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - The type of the computer use tool. Always `computer_use_preview`. + Omitting `parameters` defines a function with an empty parameter list. - - `"computer_use_preview"` + - `strict: optional boolean` - - `WebSearch object { type, filters, search_context_size, user_location }` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-calling). - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + - `type: "function"` - - `type: "web_search" or "web_search_2025_08_26"` + The type of tool being defined: `function` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `"function"` - - `"web_search"` + - `response_format: optional AssistantResponseFormatOption` - - `"web_search_2025_08_26"` + Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `filters: optional object { allowed_domains }` + Setting to `{ "type": "json_schema", "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). - Filters for the search. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `allowed_domains: optional array of string` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `"auto"` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + `auto` is the default value - - `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. + - `ResponseFormatText object { type }` - - `"low"` + Default response format. Used to generate text responses. - - `"medium"` + - `type: "text"` - - `"high"` + The type of response format being defined. Always `text`. - - `user_location: optional object { city, country, region, 2 more }` + - `"text"` - The approximate location of the user. + - `ResponseFormatJSONObject object { type }` - - `city: optional string` + 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. - Free text input for the city of the user, e.g. `San Francisco`. + - `type: "json_object"` - - `country: optional string` + The type of response format being defined. Always `json_object`. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `"json_object"` - - `region: optional string` + - `ResponseFormatJSONSchema object { json_schema, type }` - Free text input for the region of the user, e.g. `California`. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `timezone: optional string` + - `json_schema: object { name, description, schema, strict }` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + Structured Outputs configuration options, including a JSON Schema. - - `type: optional "approximate"` + - `name: string` - The type of location approximation. Always `approximate`. + 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. - - `"approximate"` + - `description: optional string` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + A description of what the response format is for, used by the model to + determine how to respond in the format. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + - `schema: optional map[unknown]` - - `server_label: string` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - A label for this MCP server, used to identify it in tool calls. + - `strict: optional boolean` - - `type: "mcp"` + 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 type of the MCP tool. Always `mcp`. + - `type: "json_schema"` - - `"mcp"` + The type of response format being defined. Always `json_schema`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"json_schema"` - The tool invocation context(s). + - `temperature: optional number` - - `"direct"` + 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. - - `"programmatic"` + - `tool_resources: optional object { code_interpreter, file_search }` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - List of allowed tool names or a filter object. + - `code_interpreter: optional object { file_ids }` - - `McpAllowedTools = array of string` + - `file_ids: optional array of string` - A string array of allowed tool names + A list of [file](/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. - - `McpToolFilter object { read_only, tool_names }` + - `file_search: optional object { vector_store_ids }` - A filter object to specify which tools are allowed. + - `vector_store_ids: optional array of string` - - `read_only: optional boolean` + The ID of the [vector store](/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. - 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. + - `top_p: optional number` - - `tool_names: optional array of string` + 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. - List of allowed tool names. + We generally recommend altering this or temperature but not both. - - `authorization: optional string` +### Assistant Deleted - 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. +- `AssistantDeleted object { id, deleted, object }` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `id: string` - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + - `deleted: boolean` - Currently supported `connector_id` values are: + - `object: "assistant.deleted"` - - 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` + - `"assistant.deleted"` - - `"connector_dropbox"` +### Assistant Stream Event - - `"connector_gmail"` +- `AssistantStreamEvent = object { data, event, enabled } or object { data, event } or object { data, event } or 22 more` - - `"connector_googlecalendar"` + Represents an event emitted when streaming a Run. - - `"connector_googledrive"` + Each event in a server-sent events stream has an `event` and `data` property: - - `"connector_microsoftteams"` + ``` + event: thread.created + data: {"id": "thread_123", "object": "thread", ...} + ``` - - `"connector_outlookcalendar"` + We emit events whenever a new object is created, transitions to a new state, or is being + streamed in parts (deltas). For example, we emit `thread.run.created` when a new run + is created, `thread.run.completed` when a run completes, and so on. When an Assistant chooses + to create a message during a run, we emit a `thread.message.created event`, a + `thread.message.in_progress` event, many `thread.message.delta` events, and finally a + `thread.message.completed` event. - - `"connector_outlookemail"` + We may add additional events over time, so we recommend handling unknown events gracefully + in your code. See the [Assistants API quickstart](/docs/assistants/overview) to learn how to + integrate the Assistants API with streaming. - - `"connector_sharepoint"` + - `ThreadCreated object { data, event, enabled }` - - `defer_loading: optional boolean` + Occurs when a new [thread](/docs/api-reference/threads/object) is created. - Whether this MCP tool is deferred and discovered via tool search. + - `data: Thread` - - `headers: optional map[string]` + Represents a thread that contains [messages](/docs/api-reference/messages). - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `id: string` - - `require_approval: optional object { always, never } or "always" or "never"` + The identifier, which can be referenced in API endpoints. - Specify which of the MCP server's tools require approval. + - `created_at: number` - - `McpToolApprovalFilter object { always, never }` + The Unix timestamp (in seconds) for when the thread was created. - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `metadata: Metadata` - - `always: optional object { read_only, 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. - A filter object to specify which tools are allowed. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `read_only: optional boolean` + - `object: "thread"` - 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 object type, which is always `thread`. - - `tool_names: optional array of string` + - `"thread"` - List of allowed tool names. + - `tool_resources: object { code_interpreter, file_search }` - - `never: optional object { read_only, tool_names }` + A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - A filter object to specify which tools are allowed. + - `code_interpreter: optional object { file_ids }` - - `read_only: optional boolean` + - `file_ids: optional 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. + A list of [file](/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. - - `tool_names: optional array of string` + - `file_search: optional object { vector_store_ids }` - List of allowed tool names. + - `vector_store_ids: optional array of string` - - `McpToolApprovalSetting = "always" or "never"` + The [vector store](/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. - 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. + - `event: "thread.created"` - - `"always"` + - `"thread.created"` - - `"never"` + - `enabled: optional boolean` - - `server_description: optional string` + Whether to enable input audio transcription. - Optional description of the MCP server, used to provide more context. + - `ThreadRunCreated object { data, event }` - - `server_url: optional string` + Occurs when a new [run](/docs/api-reference/runs/object) is created. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `data: Run` - - `tunnel_id: optional string` + Represents an execution run on a [thread](/docs/api-reference/threads). - 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. + - `id: string` - - `CodeInterpreter object { container, type, allowed_callers }` + The identifier, which can be referenced in API endpoints. - A tool that runs Python code to help generate a response to a prompt. + - `assistant_id: string` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. - 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. + - `cancelled_at: number` - - `string` + The Unix timestamp (in seconds) for when the run was cancelled. - The container ID. + - `completed_at: number` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + The Unix timestamp (in seconds) for when the run was completed. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `created_at: number` - - `type: "auto"` + The Unix timestamp (in seconds) for when the run was created. - Always `auto`. + - `expires_at: number` - - `"auto"` + The Unix timestamp (in seconds) for when the run will expire. - - `file_ids: optional array of string` + - `failed_at: number` - An optional list of uploaded files to make available to your code. + The Unix timestamp (in seconds) for when the run failed. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `incomplete_details: object { reason }` - The memory limit for the code interpreter container. + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `"1g"` + - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` - - `"4g"` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `"16g"` + - `"max_completion_tokens"` - - `"64g"` + - `"max_prompt_tokens"` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `instructions: string` - Network access policy for the container. + The instructions that the [assistant](/docs/api-reference/assistants) used for this run. - - `BetaContainerNetworkPolicyDisabled object { type }` + - `last_error: object { code, message }` - - `type: "disabled"` + The last error associated with this run. Will be `null` if there are no errors. - Disable outbound network access. Always `disabled`. + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` - - `"disabled"` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `"server_error"` - - `allowed_domains: array of string` + - `"rate_limit_exceeded"` - A list of allowed domains when type is `allowlist`. + - `"invalid_prompt"` - - `type: "allowlist"` + - `message: string` - Allow outbound network access only to specified domains. Always `allowlist`. + A human-readable description of the error. - - `"allowlist"` + - `max_completion_tokens: number` - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + The maximum number of completion tokens specified to have been used over the course of the run. - Optional domain-scoped secrets for allowlisted domains. + - `max_prompt_tokens: number` - - `domain: string` + The maximum number of prompt tokens specified to have been used over the course of the run. - The domain associated with the secret. + - `metadata: Metadata` - - `name: 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 name of the secret to inject for the domain. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `value: string` + - `model: string` - The secret value to inject for the domain. + The model that the [assistant](/docs/api-reference/assistants) used for this run. - - `type: "code_interpreter"` + - `object: "thread.run"` - The type of the code interpreter tool. Always `code_interpreter`. + The object type, which is always `thread.run`. - - `"code_interpreter"` + - `"thread.run"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `parallel_tool_calls: boolean` - The tool invocation context(s). + Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `"direct"` + - `required_action: object { submit_tool_outputs, type }` - - `"programmatic"` + Details on the action required to continue the run. Will be `null` if no action is required. - - `ProgrammaticToolCalling object { type }` + - `submit_tool_outputs: object { tool_calls }` - - `type: "programmatic_tool_calling"` + Details on the tool outputs needed for this run to continue. - The type of the tool. Always `programmatic_tool_calling`. + - `tool_calls: array of RequiredActionFunctionToolCall` - - `"programmatic_tool_calling"` + A list of the relevant tool calls. - - `ImageGeneration object { type, action, background, 9 more }` + - `id: string` - A tool that generates images using the GPT image models. + The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](/docs/api-reference/runs/submitToolOutputs) endpoint. - - `type: "image_generation"` + - `function: object { arguments, name }` - The type of the image generation tool. Always `image_generation`. + The function definition. - - `"image_generation"` + - `arguments: string` - - `action: optional "generate" or "edit" or "auto"` + The arguments that the model expects you to pass to the function. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `name: string` - - `"generate"` + The name of the function. - - `"edit"` + - `type: "function"` - - `"auto"` + The type of tool call the output is required for. For now, this is always `function`. - - `background: optional "transparent" or "opaque" or "auto"` + - `"function"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + - `type: "submit_tool_outputs"` - - `"transparent"` + For now, this is always `submit_tool_outputs`. - - `"opaque"` + - `"submit_tool_outputs"` - - `"auto"` + - `response_format: AssistantResponseFormatOption` - - `input_fidelity: optional "high" or "low"` + Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - 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`. + Setting to `{ "type": "json_schema", "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). - - `"high"` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `"low"` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `input_image_mask: optional object { file_id, image_url }` + - `"auto"` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + `auto` is the default value - - `file_id: optional string` + - `"auto"` - File ID for the mask image. + - `ResponseFormatText object { type }` - - `image_url: optional string` + Default response format. Used to generate text responses. - Base64-encoded mask image. + - `type: "text"` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + The type of response format being defined. Always `text`. - The image generation model to use. Default: `gpt-image-1`. + - `"text"` - - `string` + - `ResponseFormatJSONObject object { type }` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + 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 image generation model to use. Default: `gpt-image-1`. + - `type: "json_object"` - - `"gpt-image-1"` + The type of response format being defined. Always `json_object`. - - `"gpt-image-1-mini"` + - `"json_object"` - - `"gpt-image-1.5"` + - `ResponseFormatJSONSchema object { json_schema, type }` - - `moderation: optional "auto" or "low"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - Moderation level for the generated image. Default: `auto`. + - `json_schema: object { name, description, schema, strict }` - - `"auto"` + Structured Outputs configuration options, including a JSON Schema. - - `"low"` + - `name: string` - - `output_compression: optional number` + 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. - Compression level for the output image. Default: 100. + - `description: optional string` - - `output_format: optional "png" or "webp" or "jpeg"` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `schema: optional map[unknown]` - - `"png"` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `"webp"` + - `strict: optional boolean` - - `"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). - - `partial_images: optional number` + - `type: "json_schema"` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The type of response format being defined. Always `json_schema`. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `"json_schema"` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `started_at: number` - - `"low"` + The Unix timestamp (in seconds) for when the run was started. - - `"medium"` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - - `"high"` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `"auto"` + - `"queued"` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `"in_progress"` - 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`. + - `"requires_action"` - - `string` + - `"cancelling"` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `"cancelled"` - 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`. + - `"failed"` - - `"1024x1024"` + - `"completed"` - - `"1024x1536"` + - `"incomplete"` - - `"1536x1024"` + - `"expired"` - - `"auto"` + - `thread_id: string` - - `LocalShell object { type }` + The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. - A tool that allows the model to execute shell commands in a local environment. + - `tool_choice: AssistantToolChoiceOption` - - `type: "local_shell"` + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - The type of the local shell tool. Always `local_shell`. + - `"none" or "auto" or "required"` - - `"local_shell"` + `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. - - `Shell object { type, allowed_callers, environment }` + - `"none"` - A tool that allows the model to execute shell commands. + - `"auto"` - - `type: "shell"` + - `"required"` - The type of the shell tool. Always `shell`. + - `AssistantToolChoice object { type, function }` - - `"shell"` + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "function" or "code_interpreter" or "file_search"` - The tool invocation context(s). + The type of the tool. If type is `function`, the function name must be set - - `"direct"` + - `"function"` - - `"programmatic"` + - `"code_interpreter"` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `"file_search"` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `function: optional AssistantToolChoiceFunction` - - `type: "container_auto"` + - `name: string` - Automatically creates a container for this request + The name of the function to call. - - `"container_auto"` + - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` - - `file_ids: optional array of string` + The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. - An optional list of uploaded files to make available to your code. + - `CodeInterpreterTool object { type }` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `type: "code_interpreter"` - The memory limit for the container. + The type of tool being defined: `code_interpreter` - - `"1g"` + - `"code_interpreter"` - - `"4g"` + - `FileSearchTool object { type, file_search }` - - `"16g"` + - `type: "file_search"` - - `"64g"` + The type of tool being defined: `file_search` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `"file_search"` - Network access policy for the container. + - `file_search: optional object { max_num_results, ranking_options }` - - `BetaContainerNetworkPolicyDisabled object { type }` + Overrides for the file search tool. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `max_num_results: optional number` - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - An optional list of skills referenced by id or inline data. + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `BetaSkillReference object { skill_id, type, version }` + - `ranking_options: optional object { score_threshold, ranker }` - - `skill_id: string` + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - The ID of the referenced skill. + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `type: "skill_reference"` + - `score_threshold: number` - References a skill created with the /v1/skills endpoint. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `"skill_reference"` + - `ranker: optional "auto" or "default_2024_08_21"` - - `version: optional string` + The ranker to use for the file search. If not specified will use the `auto` ranker. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `"auto"` - - `BetaInlineSkill object { description, name, source, type }` + - `"default_2024_08_21"` - - `description: string` + - `FunctionTool object { function, type }` - The description of the skill. + - `function: FunctionDefinition` - `name: string` - The name of the skill. + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `source: BetaInlineSkillSource` + - `description: optional string` - Inline skill payload + A description of what the function does, used by the model to choose when and how to call the function. - - `data: string` + - `parameters: optional FunctionParameters` - Base64-encoded skill zip bundle. + The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - `media_type: "application/zip"` + Omitting `parameters` defines a function with an empty parameter list. - The media type of the inline skill payload. Must be `application/zip`. + - `strict: optional boolean` - - `"application/zip"` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-calling). - - `type: "base64"` + - `type: "function"` - The type of the inline skill source. Must be `base64`. + The type of tool being defined: `function` - - `"base64"` + - `"function"` - - `type: "inline"` + - `truncation_strategy: object { type, last_messages }` - Defines an inline skill for this request. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `"inline"` + - `type: "auto" or "last_messages"` - - `BetaLocalEnvironment object { type, skills }` + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. - - `type: "local"` + - `"auto"` - Use a local computer environment. + - `"last_messages"` - - `"local"` + - `last_messages: optional number` - - `skills: optional array of BetaLocalSkill` + The number of most recent messages from the thread when constructing the context for the run. - An optional list of skills. + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `description: string` + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - The description of the skill. + - `completion_tokens: number` - - `name: string` + Number of completion tokens used over the course of the run. - The name of the skill. + - `prompt_tokens: number` - - `path: string` + Number of prompt tokens used over the course of the run. - The path to the directory containing the skill. + - `total_tokens: number` - - `BetaContainerReference object { container_id, type }` + Total number of tokens used (prompt + completion). - - `container_id: string` + - `temperature: optional number` - The ID of the referenced container. + The sampling temperature used for this run. If not set, defaults to 1. - - `type: "container_reference"` + - `top_p: optional number` - References a container created with the /v1/containers endpoint + The nucleus sampling value used for this run. If not set, defaults to 1. - - `"container_reference"` + - `event: "thread.run.created"` - - `Custom object { name, type, allowed_callers, 3 more }` + - `"thread.run.created"` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `ThreadRunQueued object { data, event }` - - `name: string` + Occurs when a [run](/docs/api-reference/runs/object) moves to a `queued` status. - The name of the custom tool, used to identify it in tool calls. + - `data: Run` - - `type: "custom"` + Represents an execution run on a [thread](/docs/api-reference/threads). - The type of the custom tool. Always `custom`. + - `event: "thread.run.queued"` - - `"custom"` + - `"thread.run.queued"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `ThreadRunInProgress object { data, event }` - The tool invocation context(s). + Occurs when a [run](/docs/api-reference/runs/object) moves to an `in_progress` status. - - `"direct"` + - `data: Run` - - `"programmatic"` + Represents an execution run on a [thread](/docs/api-reference/threads). - - `defer_loading: optional boolean` + - `event: "thread.run.in_progress"` - Whether this tool should be deferred and discovered via tool search. + - `"thread.run.in_progress"` - - `description: optional string` + - `ThreadRunRequiresAction object { data, event }` - Optional description of the custom tool, used to provide more context. + Occurs when a [run](/docs/api-reference/runs/object) moves to a `requires_action` status. - - `format: optional object { type } or object { definition, syntax, type }` + - `data: Run` - The input format for the custom tool. Default is unconstrained text. + Represents an execution run on a [thread](/docs/api-reference/threads). - - `Text object { type }` + - `event: "thread.run.requires_action"` - Unconstrained free-form text. + - `"thread.run.requires_action"` - - `type: "text"` + - `ThreadRunCompleted object { data, event }` - Unconstrained text format. Always `text`. + Occurs when a [run](/docs/api-reference/runs/object) is completed. - - `"text"` + - `data: Run` - - `Grammar object { definition, syntax, type }` + Represents an execution run on a [thread](/docs/api-reference/threads). - A grammar defined by the user. + - `event: "thread.run.completed"` - - `definition: string` + - `"thread.run.completed"` - The grammar definition. + - `ThreadRunIncomplete object { data, event }` - - `syntax: "lark" or "regex"` + Occurs when a [run](/docs/api-reference/runs/object) ends with status `incomplete`. - The syntax of the grammar definition. One of `lark` or `regex`. + - `data: Run` - - `"lark"` + Represents an execution run on a [thread](/docs/api-reference/threads). - - `"regex"` + - `event: "thread.run.incomplete"` - - `type: "grammar"` + - `"thread.run.incomplete"` - Grammar format. Always `grammar`. + - `ThreadRunFailed object { data, event }` - - `"grammar"` + Occurs when a [run](/docs/api-reference/runs/object) fails. - - `Namespace object { description, name, tools, type }` + - `data: Run` - Groups function/custom tools under a shared namespace. + Represents an execution run on a [thread](/docs/api-reference/threads). - - `description: string` + - `event: "thread.run.failed"` - A description of the namespace shown to the model. + - `"thread.run.failed"` - - `name: string` + - `ThreadRunCancelling object { data, event }` - The namespace name used in tool calls (for example, `crm`). + Occurs when a [run](/docs/api-reference/runs/object) moves to a `cancelling` status. - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `data: Run` - The function/custom tools available inside this namespace. + Represents an execution run on a [thread](/docs/api-reference/threads). - - `Function object { name, type, allowed_callers, 5 more }` + - `event: "thread.run.cancelling"` - - `name: string` + - `"thread.run.cancelling"` - - `type: "function"` + - `ThreadRunCancelled object { data, event }` - - `"function"` + Occurs when a [run](/docs/api-reference/runs/object) is cancelled. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `data: Run` - The tool invocation context(s). + Represents an execution run on a [thread](/docs/api-reference/threads). - - `"direct"` + - `event: "thread.run.cancelled"` - - `"programmatic"` + - `"thread.run.cancelled"` - - `defer_loading: optional boolean` + - `ThreadRunExpired object { data, event }` - Whether this function should be deferred and discovered via tool search. + Occurs when a [run](/docs/api-reference/runs/object) expires. - - `description: optional string` + - `data: Run` - - `output_schema: optional map[unknown]` + Represents an execution run on a [thread](/docs/api-reference/threads). - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `event: "thread.run.expired"` - - `parameters: optional unknown` + - `"thread.run.expired"` - - `strict: optional boolean` + - `ThreadRunStepCreated object { data, event }` - 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. + Occurs when a [run step](/docs/api-reference/run-steps/step-object) is created. - - `Custom object { name, type, allowed_callers, 3 more }` + - `data: RunStep` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + Represents a step in execution of a run. - - `name: string` + - `id: string` - The name of the custom tool, used to identify it in tool calls. + The identifier of the run step, which can be referenced in API endpoints. - - `type: "custom"` + - `assistant_id: string` - The type of the custom tool. Always `custom`. + The ID of the [assistant](/docs/api-reference/assistants) associated with the run step. - - `"custom"` + - `cancelled_at: number` - - `allowed_callers: optional array of "direct" or "programmatic"` + The Unix timestamp (in seconds) for when the run step was cancelled. - The tool invocation context(s). + - `completed_at: number` - - `"direct"` + The Unix timestamp (in seconds) for when the run step completed. - - `"programmatic"` + - `created_at: number` - - `defer_loading: optional boolean` + The Unix timestamp (in seconds) for when the run step was created. - Whether this tool should be deferred and discovered via tool search. + - `expired_at: number` - - `description: optional string` + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - Optional description of the custom tool, used to provide more context. + - `failed_at: number` - - `format: optional object { type } or object { definition, syntax, type }` + The Unix timestamp (in seconds) for when the run step failed. - The input format for the custom tool. Default is unconstrained text. + - `last_error: object { code, message }` - - `Text object { type }` + The last error associated with this run step. Will be `null` if there are no errors. - Unconstrained free-form text. + - `code: "server_error" or "rate_limit_exceeded"` - - `type: "text"` + One of `server_error` or `rate_limit_exceeded`. - Unconstrained text format. Always `text`. + - `"server_error"` - - `"text"` + - `"rate_limit_exceeded"` - - `Grammar object { definition, syntax, type }` + - `message: string` - A grammar defined by the user. + A human-readable description of the error. - - `definition: string` + - `metadata: Metadata` - The grammar definition. + 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. - - `syntax: "lark" or "regex"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The syntax of the grammar definition. One of `lark` or `regex`. + - `object: "thread.run.step"` - - `"lark"` + The object type, which is always `thread.run.step`. - - `"regex"` + - `"thread.run.step"` - - `type: "grammar"` + - `run_id: string` - Grammar format. Always `grammar`. + The ID of the [run](/docs/api-reference/runs) that this run step is a part of. - - `"grammar"` + - `status: "in_progress" or "cancelled" or "failed" or 2 more` - - `type: "namespace"` + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - The type of the tool. Always `namespace`. + - `"in_progress"` - - `"namespace"` + - `"cancelled"` - - `ToolSearch object { type, description, execution, parameters }` + - `"failed"` - Hosted or BYOT tool search configuration for deferred tools. + - `"completed"` - - `type: "tool_search"` + - `"expired"` - The type of the tool. Always `tool_search`. + - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` - - `"tool_search"` + The details of the run step. - - `description: optional string` + - `MessageCreationStepDetails object { message_creation, type }` - Description shown to the model for a client-executed tool search tool. + Details of the message creation by the run step. - - `execution: optional "server" or "client"` + - `message_creation: object { message_id }` - Whether tool search is executed by the server or by the client. + - `message_id: string` - - `"server"` + The ID of the message that was created by this run step. - - `"client"` + - `type: "message_creation"` - - `parameters: optional unknown` + Always `message_creation`. - Parameter schema for a client-executed tool search tool. + - `"message_creation"` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `ToolCallsStepDetails object { tool_calls, 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). + Details of the tool call. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `tool_calls: array of CodeInterpreterToolCall or FileSearchToolCall or FunctionToolCall` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - - `"web_search_preview"` + - `CodeInterpreterToolCall object { id, code_interpreter, type }` - - `"web_search_preview_2025_03_11"` + Details of the Code Interpreter tool call the run step was involved in. - - `search_content_types: optional array of "text" or "image"` + - `id: string` - - `"text"` + The ID of the tool call. - - `"image"` + - `code_interpreter: object { input, outputs }` - - `search_context_size: optional "low" or "medium" or "high"` + The Code Interpreter tool call definition. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `input: string` - - `"low"` + The input to the Code Interpreter tool call. - - `"medium"` + - `outputs: array of object { logs, type } or object { image, type }` - - `"high"` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `user_location: optional object { type, city, country, 2 more }` + - `CodeInterpreterLogOutput object { logs, type }` - The user's location. + Text output from the Code Interpreter tool call as part of a run step. - - `type: "approximate"` + - `logs: string` - The type of location approximation. Always `approximate`. + The text output from the Code Interpreter tool call. - - `"approximate"` + - `type: "logs"` - - `city: optional string` + Always `logs`. - Free text input for the city of the user, e.g. `San Francisco`. + - `"logs"` - - `country: optional string` + - `CodeInterpreterImageOutput object { image, type }` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `image: object { file_id }` - - `region: optional string` + - `file_id: string` - Free text input for the region of the user, e.g. `California`. + The [file](/docs/api-reference/files) ID of the image. - - `timezone: optional string` + - `type: "image"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + Always `image`. - - `ApplyPatch object { type, allowed_callers }` + - `"image"` - Allows the assistant to create, delete, or update files using unified diffs. + - `type: "code_interpreter"` - - `type: "apply_patch"` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - The type of the tool. Always `apply_patch`. + - `"code_interpreter"` - - `"apply_patch"` + - `FileSearchToolCall object { id, file_search, type }` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `id: string` - The tool invocation context(s). + The ID of the tool call object. - - `"direct"` + - `file_search: object { ranking_options, results }` - - `"programmatic"` + For now, this is always going to be an empty object. - - `type: "tool_search_output"` + - `ranking_options: optional object { ranker, score_threshold }` - The item type. Always `tool_search_output`. + The ranking options for the file search. - - `"tool_search_output"` + - `ranker: "auto" or "default_2024_08_21"` - - `id: optional string` + The ranker to use for the file search. If not specified will use the `auto` ranker. - The unique ID of this tool search output. + - `"auto"` - - `agent: optional object { agent_name }` + - `"default_2024_08_21"` - The agent that produced this item. + - `score_threshold: number` - - `agent_name: string` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The canonical name of the agent that produced this item. + - `results: optional array of object { file_id, file_name, score, content }` - - `call_id: optional string` + The results of the file search. - The unique ID of the tool search call generated by the model. + - `file_id: string` - - `execution: optional "server" or "client"` + The ID of the file that result was found in. - Whether tool search was executed by the server or by the client. + - `file_name: string` - - `"server"` + The name of the file that result was found in. - - `"client"` + - `score: number` - - `status: optional "in_progress" or "completed" or "incomplete"` + The score of the result. All values must be a floating point number between 0 and 1. - The status of the tool search output. + - `content: optional array of object { text, type }` - - `"in_progress"` + The content of the result that was found. The content is only included if requested via the include query parameter. - - `"completed"` + - `text: optional string` - - `"incomplete"` + The text content of the file. - - `AdditionalTools object { role, tools, type, 2 more }` + - `type: optional "text"` - - `role: "developer"` + The type of the content. - The role that provided the additional tools. Only `developer` is supported. + - `"text"` - - `"developer"` + - `type: "file_search"` - - `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 type of tool call. This is always going to be `file_search` for this type of tool call. - A list of additional tools made available at this item. + - `"file_search"` - - `Function object { name, parameters, strict, 5 more }` + - `FunctionToolCall object { id, function, type }` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `id: string` - - `name: string` + The ID of the tool call object. - The name of the function to call. + - `function: object { arguments, name, output }` - - `parameters: map[unknown]` + The definition of the function that was called. - A JSON schema object describing the parameters of the function. + - `arguments: string` - - `strict: boolean` + The arguments passed to the function. - Whether strict parameter validation is enforced for this function tool. + - `name: string` + + The name of the function. + + - `output: string` + + The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. - `type: "function"` - The type of the function tool. Always `function`. + The type of tool call. This is always going to be `function` for this type of tool call. - `"function"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "tool_calls"` - The tool invocation context(s). + Always `tool_calls`. - - `"direct"` + - `"tool_calls"` - - `"programmatic"` + - `thread_id: string` - - `defer_loading: optional boolean` + The ID of the [thread](/docs/api-reference/threads) that was run. - Whether this function is deferred and loaded via tool search. + - `type: "message_creation" or "tool_calls"` - - `description: optional string` + The type of run step, which can be either `message_creation` or `tool_calls`. - A description of the function. Used by the model to determine whether or not to call the function. + - `"message_creation"` - - `output_schema: optional map[unknown]` + - `"tool_calls"` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - 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). + - `completion_tokens: number` - - `type: "file_search"` + Number of completion tokens used over the course of the run step. - The type of the file search tool. Always `file_search`. + - `prompt_tokens: number` - - `"file_search"` + Number of prompt tokens used over the course of the run step. - - `vector_store_ids: array of string` + - `total_tokens: number` - The IDs of the vector stores to search. + Total number of tokens used (prompt + completion). - - `filters: optional object { key, type, value } or object { filters, type }` + - `event: "thread.run.step.created"` - A filter to apply. + - `"thread.run.step.created"` - - `ComparisonFilter object { key, type, value }` + - `ThreadRunStepInProgress object { data, event }` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + Occurs when a [run step](/docs/api-reference/run-steps/step-object) moves to an `in_progress` state. - - `key: string` + - `data: RunStep` - The key to compare against the value. + Represents a step in execution of a run. - - `type: "eq" or "ne" or "gt" or 5 more` + - `event: "thread.run.step.in_progress"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"thread.run.step.in_progress"` - - `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 + - `ThreadRunStepDelta object { data, event }` - - `"eq"` + Occurs when parts of a [run step](/docs/api-reference/run-steps/step-object) are being streamed. - - `"ne"` + - `data: RunStepDeltaEvent` - - `"gt"` + Represents a run step delta i.e. any changed fields on a run step during streaming. - - `"gte"` + - `id: string` - - `"lt"` + The identifier of the run step, which can be referenced in API endpoints. - - `"lte"` + - `delta: object { step_details }` - - `"in"` + The delta containing the fields that have changed on the run step. - - `"nin"` + - `step_details: optional RunStepDeltaMessageDelta or ToolCallDeltaObject` - - `value: string or number or boolean or array of string or number` + The details of the run step. - The value to compare against the attribute key; supports string, number, or boolean types. + - `RunStepDeltaMessageDelta object { type, message_creation }` - - `string` + Details of the message creation by the run step. - - `number` + - `type: "message_creation"` - - `boolean` + Always `message_creation`. - - `array of string or number` + - `"message_creation"` - - `string` + - `message_creation: optional object { message_id }` - - `number` + - `message_id: optional string` - - `CompoundFilter object { filters, type }` + The ID of the message that was created by this run step. - Combine multiple filters using `and` or `or`. + - `ToolCallDeltaObject object { type, tool_calls }` - - `filters: array of object { key, type, value } or unknown` + Details of the tool call. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `type: "tool_calls"` - - `ComparisonFilter object { key, type, value }` + Always `tool_calls`. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"tool_calls"` - - `key: string` + - `tool_calls: optional array of CodeInterpreterToolCallDelta or FileSearchToolCallDelta or FunctionToolCallDelta` - The key to compare against the value. + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - - `type: "eq" or "ne" or "gt" or 5 more` + - `CodeInterpreterToolCallDelta object { index, type, id, code_interpreter }` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + Details of the Code Interpreter tool call the run step was involved in. - - `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 + - `index: number` - - `"eq"` + The index of the tool call in the tool calls array. - - `"ne"` + - `type: "code_interpreter"` - - `"gt"` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `"gte"` + - `"code_interpreter"` - - `"lt"` + - `id: optional string` - - `"lte"` + The ID of the tool call. - - `"in"` + - `code_interpreter: optional object { input, outputs }` - - `"nin"` + The Code Interpreter tool call definition. - - `value: string or number or boolean or array of string or number` + - `input: optional string` - The value to compare against the attribute key; supports string, number, or boolean types. + The input to the Code Interpreter tool call. - - `string` + - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` - - `number` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `boolean` + - `CodeInterpreterLogs object { index, type, logs }` - - `array of string or number` + Text output from the Code Interpreter tool call as part of a run step. - - `string` + - `index: number` - - `number` + The index of the output in the outputs array. - - `unknown` + - `type: "logs"` - - `type: "and" or "or"` + Always `logs`. - Type of operation: `and` or `or`. + - `"logs"` - - `"and"` + - `logs: optional string` - - `"or"` + The text output from the Code Interpreter tool call. - - `max_num_results: optional number` + - `CodeInterpreterOutputImage object { index, type, image }` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `index: number` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + The index of the output in the outputs array. - Ranking options for search. + - `type: "image"` - - `hybrid_search: optional object { embedding_weight, text_weight }` + Always `image`. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `"image"` - - `embedding_weight: number` + - `image: optional object { file_id }` - The weight of the embedding in the reciprocal ranking fusion. + - `file_id: optional string` - - `text_weight: number` + The [file](/docs/api-reference/files) ID of the image. - The weight of the text in the reciprocal ranking fusion. + - `FileSearchToolCallDelta object { file_search, index, type, id }` - - `ranker: optional "auto" or "default-2024-11-15"` + - `file_search: unknown` - The ranker to use for the file search. + For now, this is always going to be an empty object. - - `"auto"` + - `index: number` - - `"default-2024-11-15"` + The index of the tool call in the tool calls array. - - `score_threshold: optional number` + - `type: "file_search"` - 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 tool call. This is always going to be `file_search` for this type of tool call. - - `Computer object { type }` + - `"file_search"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `id: optional string` - - `type: "computer"` + The ID of the tool call object. - The type of the computer tool. Always `computer`. + - `FunctionToolCallDelta object { index, type, id, function }` - - `"computer"` + - `index: number` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + The index of the tool call in the tool calls array. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `type: "function"` - - `display_height: number` + The type of tool call. This is always going to be `function` for this type of tool call. - The height of the computer display. + - `"function"` - - `display_width: number` + - `id: optional string` - The width of the computer display. + The ID of the tool call object. - - `environment: "windows" or "mac" or "linux" or 2 more` + - `function: optional object { arguments, name, output }` - The type of computer environment to control. + The definition of the function that was called. - - `"windows"` + - `arguments: optional string` - - `"mac"` + The arguments passed to the function. - - `"linux"` + - `name: optional string` - - `"ubuntu"` + The name of the function. - - `"browser"` + - `output: optional string` - - `type: "computer_use_preview"` + The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. - The type of the computer use tool. Always `computer_use_preview`. + - `object: "thread.run.step.delta"` - - `"computer_use_preview"` + The object type, which is always `thread.run.step.delta`. - - `WebSearch object { type, filters, search_context_size, user_location }` + - `"thread.run.step.delta"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + - `event: "thread.run.step.delta"` - - `type: "web_search" or "web_search_2025_08_26"` + - `"thread.run.step.delta"` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `ThreadRunStepCompleted object { data, event }` - - `"web_search"` + Occurs when a [run step](/docs/api-reference/run-steps/step-object) is completed. - - `"web_search_2025_08_26"` + - `data: RunStep` - - `filters: optional object { allowed_domains }` + Represents a step in execution of a run. - Filters for the search. + - `event: "thread.run.step.completed"` - - `allowed_domains: optional array of string` + - `"thread.run.step.completed"` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `ThreadRunStepFailed object { data, event }` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + Occurs when a [run step](/docs/api-reference/run-steps/step-object) fails. - - `search_context_size: optional "low" or "medium" or "high"` + - `data: RunStep` - 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. + Represents a step in execution of a run. - - `"low"` + - `event: "thread.run.step.failed"` - - `"medium"` + - `"thread.run.step.failed"` - - `"high"` + - `ThreadRunStepCancelled object { data, event }` - - `user_location: optional object { city, country, region, 2 more }` + Occurs when a [run step](/docs/api-reference/run-steps/step-object) is cancelled. - The approximate location of the user. + - `data: RunStep` - - `city: optional string` + Represents a step in execution of a run. - Free text input for the city of the user, e.g. `San Francisco`. + - `event: "thread.run.step.cancelled"` - - `country: optional string` + - `"thread.run.step.cancelled"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `ThreadRunStepExpired object { data, event }` - - `region: optional string` + Occurs when a [run step](/docs/api-reference/run-steps/step-object) expires. - Free text input for the region of the user, e.g. `California`. + - `data: RunStep` - - `timezone: optional string` + Represents a step in execution of a run. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `event: "thread.run.step.expired"` - - `type: optional "approximate"` + - `"thread.run.step.expired"` - The type of location approximation. Always `approximate`. + - `ThreadMessageCreated object { data, event }` - - `"approximate"` + Occurs when a [message](/docs/api-reference/messages/object) is created. - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `data: Message` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + Represents a message within a [thread](/docs/api-reference/threads). - - `server_label: string` + - `id: string` - A label for this MCP server, used to identify it in tool calls. + The identifier, which can be referenced in API endpoints. - - `type: "mcp"` + - `assistant_id: string` - The type of the MCP tool. Always `mcp`. + If applicable, the ID of the [assistant](/docs/api-reference/assistants) that authored this message. - - `"mcp"` + - `attachments: array of object { file_id, tools }` - - `allowed_callers: optional array of "direct" or "programmatic"` + A list of files attached to the message, and the tools they were added to. - The tool invocation context(s). + - `file_id: optional string` - - `"direct"` + The ID of the file to attach to the message. - - `"programmatic"` + - `tools: optional array of CodeInterpreterTool or object { type }` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + The tools to add this file to. - List of allowed tool names or a filter object. + - `CodeInterpreterTool object { type }` - - `McpAllowedTools = array of string` + - `FileSearchTool object { type }` - A string array of allowed tool names + - `type: "file_search"` - - `McpToolFilter object { read_only, tool_names }` + The type of tool being defined: `file_search` - A filter object to specify which tools are allowed. + - `"file_search"` - - `read_only: optional boolean` + - `completed_at: 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 Unix timestamp (in seconds) for when the message was completed. - - `tool_names: optional array of string` + - `content: array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlock or RefusalContentBlock` - List of allowed tool names. + The content of the message in array of text and/or images. - - `authorization: optional string` + - `ImageFileContentBlock object { image_file, type }` - 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. + References an image [File](/docs/api-reference/files) in the content of a message. - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `image_file: ImageFile` - 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). + - `file_id: string` - Currently supported `connector_id` values are: + The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `detail: optional "auto" or "low" or "high"` - - `"connector_dropbox"` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `"connector_gmail"` + - `"auto"` - - `"connector_googlecalendar"` + - `"low"` - - `"connector_googledrive"` + - `"high"` - - `"connector_microsoftteams"` + - `type: "image_file"` - - `"connector_outlookcalendar"` + Always `image_file`. - - `"connector_outlookemail"` + - `"image_file"` - - `"connector_sharepoint"` + - `ImageURLContentBlock object { image_url, type }` - - `defer_loading: optional boolean` + References an image URL in the content of a message. - Whether this MCP tool is deferred and discovered via tool search. + - `image_url: ImageURL` - - `headers: optional map[string]` + - `url: string` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `require_approval: optional object { always, never } or "always" or "never"` + - `detail: optional "auto" or "low" or "high"` - Specify which of the MCP server's tools require approval. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `McpToolApprovalFilter object { always, never }` + - `"auto"` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `"low"` - - `always: optional object { read_only, tool_names }` + - `"high"` - A filter object to specify which tools are allowed. + - `type: "image_url"` - - `read_only: optional boolean` + The type of the content part. - 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"` - - `tool_names: optional array of string` + - `TextContentBlock object { text, type }` - List of allowed tool names. + The text content that is part of a message. - - `never: optional object { read_only, tool_names }` + - `text: Text` - A filter object to specify which tools are allowed. + - `annotations: array of FileCitationAnnotation or FilePathAnnotation` - - `read_only: optional boolean` + - `FileCitationAnnotation object { end_index, file_citation, start_index, 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 within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `tool_names: optional array of string` + - `end_index: number` - List of allowed tool names. + - `file_citation: object { file_id }` - - `McpToolApprovalSetting = "always" or "never"` + - `file_id: 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. + The ID of the specific File the citation is from. - - `"always"` + - `start_index: number` - - `"never"` + - `text: string` - - `server_description: optional string` + The text in the message content that needs to be replaced. - Optional description of the MCP server, used to provide more context. + - `type: "file_citation"` - - `server_url: optional string` + Always `file_citation`. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `"file_citation"` - - `tunnel_id: optional string` + - `FilePathAnnotation object { end_index, file_path, start_index, 2 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 URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `CodeInterpreter object { container, type, allowed_callers }` + - `end_index: number` - A tool that runs Python code to help generate a response to a prompt. + - `file_path: object { file_id }` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `file_id: string` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + The ID of the file that was generated. - - `string` + - `start_index: number` - The container ID. + - `text: string` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + The text in the message content that needs to be replaced. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `type: "file_path"` - - `type: "auto"` + Always `file_path`. - Always `auto`. + - `"file_path"` - - `"auto"` + - `value: string` - - `file_ids: optional array of string` + The data that makes up the text. - An optional list of uploaded files to make available to your code. + - `type: "text"` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + Always `text`. - The memory limit for the code interpreter container. + - `"text"` - - `"1g"` + - `RefusalContentBlock object { refusal, type }` - - `"4g"` + The refusal content generated by the assistant. - - `"16g"` + - `refusal: string` - - `"64g"` + - `type: "refusal"` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + Always `refusal`. - Network access policy for the container. + - `"refusal"` - - `BetaContainerNetworkPolicyDisabled object { type }` + - `created_at: number` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + The Unix timestamp (in seconds) for when the message was created. - - `type: "code_interpreter"` + - `incomplete_at: number` - The type of the code interpreter tool. Always `code_interpreter`. + The Unix timestamp (in seconds) for when the message was marked as incomplete. - - `"code_interpreter"` + - `incomplete_details: object { reason }` - - `allowed_callers: optional array of "direct" or "programmatic"` + On an incomplete message, details about why the message is incomplete. - The tool invocation context(s). + - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` - - `"direct"` + The reason the message is incomplete. - - `"programmatic"` + - `"content_filter"` - - `ProgrammaticToolCalling object { type }` + - `"max_tokens"` - - `type: "programmatic_tool_calling"` + - `"run_cancelled"` - The type of the tool. Always `programmatic_tool_calling`. + - `"run_expired"` - - `"programmatic_tool_calling"` + - `"run_failed"` - - `ImageGeneration object { type, action, background, 9 more }` + - `metadata: Metadata` - A tool that generates images using the GPT image models. + 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. - - `type: "image_generation"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The type of the image generation tool. Always `image_generation`. + - `object: "thread.message"` - - `"image_generation"` + The object type, which is always `thread.message`. - - `action: optional "generate" or "edit" or "auto"` + - `"thread.message"` - Whether to generate a new image or edit an existing image. Default: `auto`. + - `role: "user" or "assistant"` - - `"generate"` + The entity that produced the message. One of `user` or `assistant`. - - `"edit"` + - `"user"` - - `"auto"` + - `"assistant"` - - `background: optional "transparent" or "opaque" or "auto"` + - `run_id: string` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + The ID of the [run](/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. - - `"transparent"` + - `status: "in_progress" or "incomplete" or "completed"` - - `"opaque"` + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - - `"auto"` + - `"in_progress"` - - `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`. + - `"completed"` - - `"high"` + - `thread_id: string` - - `"low"` + The [thread](/docs/api-reference/threads) ID that this message belongs to. - - `input_image_mask: optional object { file_id, image_url }` + - `event: "thread.message.created"` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `"thread.message.created"` - - `file_id: optional string` + - `ThreadMessageInProgress object { data, event }` - File ID for the mask image. + Occurs when a [message](/docs/api-reference/messages/object) moves to an `in_progress` state. - - `image_url: optional string` + - `data: Message` - Base64-encoded mask image. + Represents a message within a [thread](/docs/api-reference/threads). - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `event: "thread.message.in_progress"` - The image generation model to use. Default: `gpt-image-1`. + - `"thread.message.in_progress"` - - `string` + - `ThreadMessageDelta object { data, event }` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + Occurs when parts of a [Message](/docs/api-reference/messages/object) are being streamed. - The image generation model to use. Default: `gpt-image-1`. + - `data: MessageDeltaEvent` - - `"gpt-image-1"` + Represents a message delta i.e. any changed fields on a message during streaming. - - `"gpt-image-1-mini"` + - `id: string` - - `"gpt-image-1.5"` + The identifier of the message, which can be referenced in API endpoints. - - `moderation: optional "auto" or "low"` + - `delta: MessageDelta` - Moderation level for the generated image. Default: `auto`. + The delta containing the fields that have changed on the Message. - - `"auto"` + - `content: optional array of ImageFileDeltaBlock or TextDeltaBlock or RefusalDeltaBlock or ImageURLDeltaBlock` - - `"low"` + The content of the message in array of text and/or images. - - `output_compression: optional number` + - `ImageFileDeltaBlock object { index, type, image_file }` - Compression level for the output image. Default: 100. + References an image [File](/docs/api-reference/files) in the content of a message. - - `output_format: optional "png" or "webp" or "jpeg"` + - `index: number` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + The index of the content part in the message. - - `"png"` + - `type: "image_file"` - - `"webp"` + Always `image_file`. - - `"jpeg"` + - `"image_file"` - - `partial_images: optional number` + - `image_file: optional ImageFileDelta` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `detail: optional "auto" or "low" or "high"` - - `quality: optional "low" or "medium" or "high" or "auto"` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `"auto"` - `"low"` - - `"medium"` - - `"high"` - - `"auto"` + - `file_id: optional string` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - 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`. + - `TextDeltaBlock object { index, type, text }` - - `string` + The text content that is part of a message. - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `index: number` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + The index of the content part in the message. - - `"1024x1024"` + - `type: "text"` - - `"1024x1536"` + Always `text`. - - `"1536x1024"` + - `"text"` - - `"auto"` + - `text: optional TextDelta` - - `LocalShell object { type }` + - `annotations: optional array of FileCitationDeltaAnnotation or FilePathDeltaAnnotation` - A tool that allows the model to execute shell commands in a local environment. + - `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` - - `type: "local_shell"` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - The type of the local shell tool. Always `local_shell`. + - `index: number` - - `"local_shell"` + The index of the annotation in the text content part. - - `Shell object { type, allowed_callers, environment }` + - `type: "file_citation"` - A tool that allows the model to execute shell commands. + Always `file_citation`. - - `type: "shell"` + - `"file_citation"` - The type of the shell tool. Always `shell`. + - `end_index: optional number` - - `"shell"` + - `file_citation: optional object { file_id, quote }` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `file_id: optional string` - The tool invocation context(s). + The ID of the specific File the citation is from. - - `"direct"` + - `quote: optional string` - - `"programmatic"` + The specific quote in the file. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `start_index: optional number` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `text: optional string` - - `BetaLocalEnvironment object { type, skills }` + The text in the message content that needs to be replaced. - - `BetaContainerReference object { container_id, type }` + - `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` - - `Custom object { name, type, allowed_callers, 3 more }` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `index: number` - - `name: string` + The index of the annotation in the text content part. - The name of the custom tool, used to identify it in tool calls. + - `type: "file_path"` - - `type: "custom"` + Always `file_path`. - The type of the custom tool. Always `custom`. + - `"file_path"` - - `"custom"` + - `end_index: optional number` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `file_path: optional object { file_id }` - The tool invocation context(s). + - `file_id: optional string` - - `"direct"` + The ID of the file that was generated. - - `"programmatic"` + - `start_index: optional number` - - `defer_loading: optional boolean` + - `text: optional string` - Whether this tool should be deferred and discovered via tool search. + The text in the message content that needs to be replaced. - - `description: optional string` + - `value: optional string` - Optional description of the custom tool, used to provide more context. + The data that makes up the text. - - `format: optional object { type } or object { definition, syntax, type }` + - `RefusalDeltaBlock object { index, type, refusal }` - The input format for the custom tool. Default is unconstrained text. + The refusal content that is part of a message. - - `Text object { type }` + - `index: number` - Unconstrained free-form text. + The index of the refusal part in the message. - - `type: "text"` + - `type: "refusal"` - Unconstrained text format. Always `text`. + Always `refusal`. - - `"text"` + - `"refusal"` - - `Grammar object { definition, syntax, type }` + - `refusal: optional string` - A grammar defined by the user. + - `ImageURLDeltaBlock object { index, type, image_url }` - - `definition: string` + References an image URL in the content of a message. - The grammar definition. + - `index: number` - - `syntax: "lark" or "regex"` + The index of the content part in the message. - The syntax of the grammar definition. One of `lark` or `regex`. + - `type: "image_url"` - - `"lark"` + Always `image_url`. - - `"regex"` + - `"image_url"` - - `type: "grammar"` + - `image_url: optional ImageURLDelta` - Grammar format. Always `grammar`. + - `detail: optional "auto" or "low" or "high"` - - `"grammar"` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `Namespace object { description, name, tools, type }` + - `"auto"` - Groups function/custom tools under a shared namespace. + - `"low"` - - `description: string` + - `"high"` - A description of the namespace shown to the model. + - `url: optional string` - - `name: string` + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The namespace name used in tool calls (for example, `crm`). + - `role: optional "user" or "assistant"` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + The entity that produced the message. One of `user` or `assistant`. - The function/custom tools available inside this namespace. + - `"user"` - - `Function object { name, type, allowed_callers, 5 more }` + - `"assistant"` - - `name: string` + - `object: "thread.message.delta"` - - `type: "function"` + The object type, which is always `thread.message.delta`. - - `"function"` + - `"thread.message.delta"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `event: "thread.message.delta"` - The tool invocation context(s). + - `"thread.message.delta"` - - `"direct"` + - `ThreadMessageCompleted object { data, event }` - - `"programmatic"` + Occurs when a [message](/docs/api-reference/messages/object) is completed. - - `defer_loading: optional boolean` + - `data: Message` - Whether this function should be deferred and discovered via tool search. + Represents a message within a [thread](/docs/api-reference/threads). - - `description: optional string` + - `event: "thread.message.completed"` - - `output_schema: optional map[unknown]` + - `"thread.message.completed"` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `ThreadMessageIncomplete object { data, event }` - - `parameters: optional unknown` + Occurs when a [message](/docs/api-reference/messages/object) ends before it is completed. - - `strict: optional boolean` + - `data: Message` - 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. + Represents a message within a [thread](/docs/api-reference/threads). - - `Custom object { name, type, allowed_callers, 3 more }` + - `event: "thread.message.incomplete"` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `"thread.message.incomplete"` - - `name: string` + - `ErrorEvent object { data, event }` - The name of the custom tool, used to identify it in tool calls. + Occurs when an [error](/docs/guides/error-codes#api-errors) occurs. This can happen due to an internal server error or a timeout. - - `type: "custom"` + - `data: ErrorObject` - The type of the custom tool. Always `custom`. + - `code: string` - - `"custom"` + - `message: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `param: string` - The tool invocation context(s). + - `type: string` - - `"direct"` + - `event: "error"` - - `"programmatic"` + - `"error"` - - `defer_loading: optional boolean` + - `DoneEvent object { data, event }` - Whether this tool should be deferred and discovered via tool search. + Occurs when a stream ends. - - `description: optional string` + - `data: "[DONE]"` - Optional description of the custom tool, used to provide more context. + - `"[DONE]"` - - `format: optional object { type } or object { definition, syntax, type }` + - `event: "done"` - The input format for the custom tool. Default is unconstrained text. + - `"done"` - - `Text object { type }` +### Code Interpreter Tool - Unconstrained free-form text. +- `CodeInterpreterTool object { type }` - - `type: "text"` + - `type: "code_interpreter"` - Unconstrained text format. Always `text`. + The type of tool being defined: `code_interpreter` - - `"text"` + - `"code_interpreter"` - - `Grammar object { definition, syntax, type }` +### File Search Tool - A grammar defined by the user. +- `FileSearchTool object { type, file_search }` - - `definition: string` + - `type: "file_search"` - The grammar definition. + The type of tool being defined: `file_search` - - `syntax: "lark" or "regex"` + - `"file_search"` - The syntax of the grammar definition. One of `lark` or `regex`. + - `file_search: optional object { max_num_results, ranking_options }` - - `"lark"` + Overrides for the file search tool. - - `"regex"` + - `max_num_results: optional number` - - `type: "grammar"` + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - Grammar format. Always `grammar`. + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `"grammar"` + - `ranking_options: optional object { score_threshold, ranker }` - - `type: "namespace"` + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - The type of the tool. Always `namespace`. + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `"namespace"` + - `score_threshold: number` - - `ToolSearch object { type, description, execution, parameters }` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - Hosted or BYOT tool search configuration for deferred tools. + - `ranker: optional "auto" or "default_2024_08_21"` - - `type: "tool_search"` + The ranker to use for the file search. If not specified will use the `auto` ranker. - The type of the tool. Always `tool_search`. + - `"auto"` - - `"tool_search"` + - `"default_2024_08_21"` - - `description: optional string` +### Function Tool - Description shown to the model for a client-executed tool search tool. +- `FunctionTool object { function, type }` - - `execution: optional "server" or "client"` + - `function: FunctionDefinition` - Whether tool search is executed by the server or by the client. + - `name: string` - - `"server"` + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `"client"` + - `description: optional string` - - `parameters: optional unknown` + A description of what the function does, used by the model to choose when and how to call the function. - Parameter schema for a client-executed tool search tool. + - `parameters: optional FunctionParameters` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - 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). + Omitting `parameters` defines a function with an empty parameter list. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `strict: optional boolean` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-calling). - - `"web_search_preview"` + - `type: "function"` - - `"web_search_preview_2025_03_11"` + The type of tool being defined: `function` - - `search_content_types: optional array of "text" or "image"` + - `"function"` - - `"text"` +### Message Stream Event - - `"image"` +- `MessageStreamEvent = object { data, event } or object { data, event } or object { data, event } or 2 more` - - `search_context_size: optional "low" or "medium" or "high"` + Occurs when a [message](/docs/api-reference/messages/object) is created. - 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. + - `ThreadMessageCreated object { data, event }` - - `"low"` + Occurs when a [message](/docs/api-reference/messages/object) is created. - - `"medium"` + - `data: Message` - - `"high"` + Represents a message within a [thread](/docs/api-reference/threads). - - `user_location: optional object { type, city, country, 2 more }` + - `id: string` - The user's location. + The identifier, which can be referenced in API endpoints. - - `type: "approximate"` + - `assistant_id: string` - The type of location approximation. Always `approximate`. + If applicable, the ID of the [assistant](/docs/api-reference/assistants) that authored this message. - - `"approximate"` + - `attachments: array of object { file_id, tools }` - - `city: optional string` + A list of files attached to the message, and the tools they were added to. - Free text input for the city of the user, e.g. `San Francisco`. + - `file_id: optional string` - - `country: optional string` + The ID of the file to attach to the message. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `tools: optional array of CodeInterpreterTool or object { type }` - - `region: optional string` + The tools to add this file to. - Free text input for the region of the user, e.g. `California`. + - `CodeInterpreterTool object { type }` - - `timezone: optional string` + - `type: "code_interpreter"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The type of tool being defined: `code_interpreter` - - `ApplyPatch object { type, allowed_callers }` + - `"code_interpreter"` - Allows the assistant to create, delete, or update files using unified diffs. + - `FileSearchTool object { type }` - - `type: "apply_patch"` + - `type: "file_search"` - The type of the tool. Always `apply_patch`. + The type of tool being defined: `file_search` - - `"apply_patch"` + - `"file_search"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `completed_at: number` - The tool invocation context(s). + The Unix timestamp (in seconds) for when the message was completed. - - `"direct"` + - `content: array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlock or RefusalContentBlock` - - `"programmatic"` + The content of the message in array of text and/or images. - - `type: "additional_tools"` + - `ImageFileContentBlock object { image_file, type }` - The item type. Always `additional_tools`. + References an image [File](/docs/api-reference/files) in the content of a message. - - `"additional_tools"` + - `image_file: ImageFile` - - `id: optional string` + - `file_id: string` - The unique ID of this additional tools item. + The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `agent: optional object { agent_name }` + - `detail: optional "auto" or "low" or "high"` - The agent that produced this item. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `agent_name: string` + - `"auto"` - The canonical name of the agent that produced this item. + - `"low"` - - `Reasoning object { id, summary, type, 4 more }` + - `"high"` - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](/docs/guides/conversation-state). + - `type: "image_file"` - - `id: string` + Always `image_file`. - The unique identifier of the reasoning content. + - `"image_file"` - - `summary: array of object { text, type }` + - `ImageURLContentBlock object { image_url, type }` - Reasoning summary content. + References an image URL in the content of a message. - - `text: string` + - `image_url: ImageURL` - A summary of the reasoning output from the model so far. + - `url: string` - - `type: "summary_text"` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The type of the object. Always `summary_text`. + - `detail: optional "auto" or "low" or "high"` - - `"summary_text"` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `type: "reasoning"` + - `"auto"` - The type of the object. Always `reasoning`. + - `"low"` - - `"reasoning"` + - `"high"` - - `agent: optional object { agent_name }` + - `type: "image_url"` - The agent that produced this item. + The type of the content part. - - `agent_name: string` + - `"image_url"` - The canonical name of the agent that produced this item. + - `TextContentBlock object { text, type }` - - `content: optional array of object { text, type }` + The text content that is part of a message. - Reasoning text content. + - `text: Text` - - `text: string` + - `annotations: array of FileCitationAnnotation or FilePathAnnotation` - The reasoning text from the model. + - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` - - `type: "reasoning_text"` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - The type of the reasoning text. Always `reasoning_text`. + - `end_index: number` - - `"reasoning_text"` + - `file_citation: object { file_id }` - - `encrypted_content: optional string` + - `file_id: 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 ID of the specific File the citation is from. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `start_index: number` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `text: string` - - `"in_progress"` + The text in the message content that needs to be replaced. - - `"completed"` + - `type: "file_citation"` - - `"incomplete"` + Always `file_citation`. - - `Compaction object { encrypted_content, type, id, agent }` + - `"file_citation"` - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` - - `encrypted_content: string` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - The encrypted content of the compaction summary. + - `end_index: number` - - `type: "compaction"` + - `file_path: object { file_id }` - The type of the item. Always `compaction`. + - `file_id: string` - - `"compaction"` + The ID of the file that was generated. - - `id: optional string` + - `start_index: number` - The ID of the compaction item. + - `text: string` - - `agent: optional object { agent_name }` + The text in the message content that needs to be replaced. - The agent that produced this item. + - `type: "file_path"` - - `agent_name: string` + Always `file_path`. - The canonical name of the agent that produced this item. + - `"file_path"` - - `ImageGenerationCall object { id, result, status, 2 more }` + - `value: string` - An image generation request made by the model. + The data that makes up the text. - - `id: string` + - `type: "text"` - The unique ID of the image generation call. + Always `text`. - - `result: string` + - `"text"` - The generated image encoded in base64. + - `RefusalContentBlock object { refusal, type }` - - `status: "in_progress" or "completed" or "generating" or "failed"` + The refusal content generated by the assistant. - The status of the image generation call. + - `refusal: string` - - `"in_progress"` + - `type: "refusal"` - - `"completed"` + Always `refusal`. - - `"generating"` + - `"refusal"` - - `"failed"` + - `created_at: number` - - `type: "image_generation_call"` + The Unix timestamp (in seconds) for when the message was created. - The type of the image generation call. Always `image_generation_call`. + - `incomplete_at: number` - - `"image_generation_call"` + The Unix timestamp (in seconds) for when the message was marked as incomplete. - - `agent: optional object { agent_name }` + - `incomplete_details: object { reason }` - The agent that produced this item. + On an incomplete message, details about why the message is incomplete. - - `agent_name: string` + - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` - The canonical name of the agent that produced this item. + The reason the message is incomplete. - - `CodeInterpreterCall object { id, code, container_id, 4 more }` + - `"content_filter"` - A tool call to run code. + - `"max_tokens"` - - `id: string` + - `"run_cancelled"` - The unique ID of the code interpreter tool call. + - `"run_expired"` - - `code: string` + - `"run_failed"` - The code to run, or null if not available. + - `metadata: Metadata` - - `container_id: string` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - The ID of the container used to run the code. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `outputs: array of object { logs, type } or object { type, url }` + - `object: "thread.message"` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + The object type, which is always `thread.message`. - - `Logs object { logs, type }` + - `"thread.message"` - The logs output from the code interpreter. + - `role: "user" or "assistant"` - - `logs: string` + The entity that produced the message. One of `user` or `assistant`. - The logs output from the code interpreter. + - `"user"` - - `type: "logs"` + - `"assistant"` - The type of the output. Always `logs`. + - `run_id: string` - - `"logs"` + The ID of the [run](/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. - - `Image object { type, url }` + - `status: "in_progress" or "incomplete" or "completed"` - The image output from the code interpreter. + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - - `type: "image"` + - `"in_progress"` - The type of the output. Always `image`. + - `"incomplete"` - - `"image"` + - `"completed"` - - `url: string` + - `thread_id: string` - The URL of the image output from the code interpreter. + The [thread](/docs/api-reference/threads) ID that this message belongs to. - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `event: "thread.message.created"` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `"thread.message.created"` - - `"in_progress"` + - `ThreadMessageInProgress object { data, event }` - - `"completed"` + Occurs when a [message](/docs/api-reference/messages/object) moves to an `in_progress` state. - - `"incomplete"` + - `data: Message` - - `"interpreting"` + Represents a message within a [thread](/docs/api-reference/threads). - - `"failed"` + - `event: "thread.message.in_progress"` - - `type: "code_interpreter_call"` + - `"thread.message.in_progress"` - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `ThreadMessageDelta object { data, event }` - - `"code_interpreter_call"` + Occurs when parts of a [Message](/docs/api-reference/messages/object) are being streamed. - - `agent: optional object { agent_name }` + - `data: MessageDeltaEvent` - The agent that produced this item. + Represents a message delta i.e. any changed fields on a message during streaming. - - `agent_name: string` + - `id: string` - The canonical name of the agent that produced this item. + The identifier of the message, which can be referenced in API endpoints. - - `LocalShellCall object { id, action, call_id, 3 more }` + - `delta: MessageDelta` - A tool call to run a command on the local shell. + The delta containing the fields that have changed on the Message. - - `id: string` + - `content: optional array of ImageFileDeltaBlock or TextDeltaBlock or RefusalDeltaBlock or ImageURLDeltaBlock` - The unique ID of the local shell call. + The content of the message in array of text and/or images. - - `action: object { command, env, type, 3 more }` + - `ImageFileDeltaBlock object { index, type, image_file }` - Execute a shell command on the server. + References an image [File](/docs/api-reference/files) in the content of a message. - - `command: array of string` + - `index: number` - The command to run. + The index of the content part in the message. - - `env: map[string]` + - `type: "image_file"` - Environment variables to set for the command. + Always `image_file`. - - `type: "exec"` + - `"image_file"` - The type of the local shell action. Always `exec`. + - `image_file: optional ImageFileDelta` - - `"exec"` + - `detail: optional "auto" or "low" or "high"` - - `timeout_ms: optional number` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - Optional timeout in milliseconds for the command. + - `"auto"` - - `user: optional string` + - `"low"` - Optional user to run the command as. + - `"high"` - - `working_directory: optional string` + - `file_id: optional string` - Optional working directory to run the command in. + The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `call_id: string` + - `TextDeltaBlock object { index, type, text }` - The unique ID of the local shell tool call generated by the model. + The text content that is part of a message. - - `status: "in_progress" or "completed" or "incomplete"` + - `index: number` - The status of the local shell call. + The index of the content part in the message. - - `"in_progress"` + - `type: "text"` - - `"completed"` + Always `text`. - - `"incomplete"` + - `"text"` - - `type: "local_shell_call"` + - `text: optional TextDelta` - The type of the local shell call. Always `local_shell_call`. + - `annotations: optional array of FileCitationDeltaAnnotation or FilePathDeltaAnnotation` - - `"local_shell_call"` + - `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` - - `agent: optional object { agent_name }` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - The agent that produced this item. + - `index: number` - - `agent_name: string` + The index of the annotation in the text content part. - The canonical name of the agent that produced this item. + - `type: "file_citation"` - - `LocalShellCallOutput object { id, output, type, 2 more }` + Always `file_citation`. - The output of a local shell tool call. + - `"file_citation"` - - `id: string` + - `end_index: optional number` - The unique ID of the local shell tool call generated by the model. + - `file_citation: optional object { file_id, quote }` - - `output: string` + - `file_id: optional string` - A JSON string of the output of the local shell tool call. + The ID of the specific File the citation is from. - - `type: "local_shell_call_output"` + - `quote: optional string` - The type of the local shell tool call output. Always `local_shell_call_output`. + The specific quote in the file. - - `"local_shell_call_output"` + - `start_index: optional number` - - `agent: optional object { agent_name }` + - `text: optional string` - The agent that produced this item. + The text in the message content that needs to be replaced. - - `agent_name: string` + - `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` - The canonical name of the agent that produced this item. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `index: number` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The index of the annotation in the text content part. - - `"in_progress"` + - `type: "file_path"` - - `"completed"` + Always `file_path`. - - `"incomplete"` + - `"file_path"` - - `ShellCall object { action, call_id, type, 5 more }` + - `end_index: optional number` - A tool representing a request to execute one or more shell commands. + - `file_path: optional object { file_id }` - - `action: object { commands, max_output_length, timeout_ms }` + - `file_id: optional string` - The shell commands and limits that describe how to run the tool call. + The ID of the file that was generated. - - `commands: array of string` + - `start_index: optional number` - Ordered shell commands for the execution environment to run. + - `text: optional string` - - `max_output_length: optional number` + The text in the message content that needs to be replaced. - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `value: optional string` - - `timeout_ms: optional number` + The data that makes up the text. - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `RefusalDeltaBlock object { index, type, refusal }` - - `call_id: string` + The refusal content that is part of a message. - The unique ID of the shell tool call generated by the model. + - `index: number` - - `type: "shell_call"` + The index of the refusal part in the message. - The type of the item. Always `shell_call`. + - `type: "refusal"` - - `"shell_call"` + Always `refusal`. - - `id: optional string` + - `"refusal"` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `refusal: optional string` - - `agent: optional object { agent_name }` + - `ImageURLDeltaBlock object { index, type, image_url }` - The agent that produced this item. + References an image URL in the content of a message. - - `agent_name: string` + - `index: number` - The canonical name of the agent that produced this item. + The index of the content part in the message. - - `caller: optional object { type } or object { caller_id, type }` + - `type: "image_url"` - The execution context that produced this tool call. + Always `image_url`. - - `Direct object { type }` + - `"image_url"` - - `type: "direct"` + - `image_url: optional ImageURLDelta` - The caller type. Always `direct`. + - `detail: optional "auto" or "low" or "high"` - - `"direct"` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `Program object { caller_id, type }` + - `"auto"` - - `caller_id: string` + - `"low"` - The call ID of the program item that produced this tool call. + - `"high"` - - `type: "program"` + - `url: optional string` - The caller type. Always `program`. + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `"program"` + - `role: optional "user" or "assistant"` - - `environment: optional BetaLocalEnvironment or BetaContainerReference` + The entity that produced the message. One of `user` or `assistant`. - The environment to execute the shell commands in. + - `"user"` - - `BetaLocalEnvironment object { type, skills }` + - `"assistant"` - - `BetaContainerReference object { container_id, type }` + - `object: "thread.message.delta"` - - `status: optional "in_progress" or "completed" or "incomplete"` + The object type, which is always `thread.message.delta`. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `"thread.message.delta"` - - `"in_progress"` + - `event: "thread.message.delta"` - - `"completed"` + - `"thread.message.delta"` - - `"incomplete"` + - `ThreadMessageCompleted object { data, event }` - - `ShellCallOutput object { call_id, output, type, 5 more }` + Occurs when a [message](/docs/api-reference/messages/object) is completed. - The streamed output items emitted by a shell tool call. + - `data: Message` - - `call_id: string` + Represents a message within a [thread](/docs/api-reference/threads). - The unique ID of the shell tool call generated by the model. + - `event: "thread.message.completed"` - - `output: array of BetaResponseFunctionShellCallOutputContent` + - `"thread.message.completed"` - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `ThreadMessageIncomplete object { data, event }` - - `outcome: object { type } or object { exit_code, type }` + Occurs when a [message](/docs/api-reference/messages/object) ends before it is completed. - The exit or timeout outcome associated with this shell call. + - `data: Message` - - `Timeout object { type }` + Represents a message within a [thread](/docs/api-reference/threads). - Indicates that the shell call exceeded its configured time limit. + - `event: "thread.message.incomplete"` - - `type: "timeout"` + - `"thread.message.incomplete"` - The outcome type. Always `timeout`. +### Run Step Stream Event - - `"timeout"` +- `RunStepStreamEvent = object { data, event } or object { data, event } or object { data, event } or 4 more` - - `Exit object { exit_code, type }` + Occurs when a [run step](/docs/api-reference/run-steps/step-object) is created. - Indicates that the shell commands finished and returned an exit code. + - `ThreadRunStepCreated object { data, event }` - - `exit_code: number` + Occurs when a [run step](/docs/api-reference/run-steps/step-object) is created. - The exit code returned by the shell process. + - `data: RunStep` - - `type: "exit"` + Represents a step in execution of a run. - The outcome type. Always `exit`. + - `id: string` - - `"exit"` + The identifier of the run step, which can be referenced in API endpoints. - - `stderr: string` + - `assistant_id: string` - Captured stderr output for the shell call. + The ID of the [assistant](/docs/api-reference/assistants) associated with the run step. - - `stdout: string` + - `cancelled_at: number` - Captured stdout output for the shell call. + The Unix timestamp (in seconds) for when the run step was cancelled. - - `type: "shell_call_output"` + - `completed_at: number` - The type of the item. Always `shell_call_output`. + The Unix timestamp (in seconds) for when the run step completed. - - `"shell_call_output"` + - `created_at: number` - - `id: optional string` + The Unix timestamp (in seconds) for when the run step was created. - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `expired_at: number` - - `agent: optional object { agent_name }` + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - The agent that produced this item. + - `failed_at: number` - - `agent_name: string` + The Unix timestamp (in seconds) for when the run step failed. - The canonical name of the agent that produced this item. + - `last_error: object { code, message }` - - `caller: optional object { type } or object { caller_id, type }` + The last error associated with this run step. Will be `null` if there are no errors. - The execution context that produced this tool call. + - `code: "server_error" or "rate_limit_exceeded"` - - `Direct object { type }` + One of `server_error` or `rate_limit_exceeded`. - - `type: "direct"` + - `"server_error"` - The caller type. Always `direct`. + - `"rate_limit_exceeded"` - - `"direct"` + - `message: string` - - `Program object { caller_id, type }` + A human-readable description of the error. - - `caller_id: string` + - `metadata: Metadata` - The call ID of the program item that produced this tool call. + 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. - - `type: "program"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The caller type. Always `program`. + - `object: "thread.run.step"` - - `"program"` + The object type, which is always `thread.run.step`. - - `max_output_length: optional number` + - `"thread.run.step"` - The maximum number of UTF-8 characters captured for this shell call's combined output. + - `run_id: string` - - `status: optional "in_progress" or "completed" or "incomplete"` + The ID of the [run](/docs/api-reference/runs) that this run step is a part of. - The status of the shell call output. + - `status: "in_progress" or "cancelled" or "failed" or 2 more` + + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - `"in_progress"` + - `"cancelled"` + + - `"failed"` + - `"completed"` - - `"incomplete"` + - `"expired"` - - `ApplyPatchCall object { call_id, operation, status, 4 more }` + - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` - A tool call representing a request to create, delete, or update files using diff patches. + The details of the run step. - - `call_id: string` + - `MessageCreationStepDetails object { message_creation, type }` - The unique ID of the apply patch tool call generated by the model. + Details of the message creation by the run step. - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `message_creation: object { message_id }` - The specific create, delete, or update instruction for the apply_patch tool call. + - `message_id: string` - - `CreateFile object { diff, path, type }` + The ID of the message that was created by this run step. - Instruction for creating a new file via the apply_patch tool. + - `type: "message_creation"` - - `diff: string` + Always `message_creation`. - Unified diff content to apply when creating the file. + - `"message_creation"` - - `path: string` + - `ToolCallsStepDetails object { tool_calls, type }` - Path of the file to create relative to the workspace root. + Details of the tool call. - - `type: "create_file"` + - `tool_calls: array of CodeInterpreterToolCall or FileSearchToolCall or FunctionToolCall` - The operation type. Always `create_file`. + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - - `"create_file"` + - `CodeInterpreterToolCall object { id, code_interpreter, type }` - - `DeleteFile object { path, type }` + Details of the Code Interpreter tool call the run step was involved in. - Instruction for deleting an existing file via the apply_patch tool. + - `id: string` - - `path: string` + The ID of the tool call. - Path of the file to delete relative to the workspace root. + - `code_interpreter: object { input, outputs }` - - `type: "delete_file"` + The Code Interpreter tool call definition. - The operation type. Always `delete_file`. + - `input: string` - - `"delete_file"` + The input to the Code Interpreter tool call. - - `UpdateFile object { diff, path, type }` + - `outputs: array of object { logs, type } or object { image, type }` - Instruction for updating an existing file via the apply_patch tool. + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `diff: string` + - `CodeInterpreterLogOutput object { logs, type }` - Unified diff content to apply to the existing file. + Text output from the Code Interpreter tool call as part of a run step. - - `path: string` + - `logs: string` - Path of the file to update relative to the workspace root. + The text output from the Code Interpreter tool call. - - `type: "update_file"` + - `type: "logs"` - The operation type. Always `update_file`. + Always `logs`. - - `"update_file"` + - `"logs"` - - `status: "in_progress" or "completed"` + - `CodeInterpreterImageOutput object { image, type }` - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `image: object { file_id }` - - `"in_progress"` + - `file_id: string` - - `"completed"` + The [file](/docs/api-reference/files) ID of the image. - - `type: "apply_patch_call"` + - `type: "image"` - The type of the item. Always `apply_patch_call`. + Always `image`. - - `"apply_patch_call"` + - `"image"` - - `id: optional string` + - `type: "code_interpreter"` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `agent: optional object { agent_name }` + - `"code_interpreter"` - The agent that produced this item. + - `FileSearchToolCall object { id, file_search, type }` - - `agent_name: string` + - `id: string` - The canonical name of the agent that produced this item. + The ID of the tool call object. - - `caller: optional object { type } or object { caller_id, type }` + - `file_search: object { ranking_options, results }` - The execution context that produced this tool call. + For now, this is always going to be an empty object. - - `Direct object { type }` + - `ranking_options: optional object { ranker, score_threshold }` - - `type: "direct"` + The ranking options for the file search. - The caller type. Always `direct`. + - `ranker: "auto" or "default_2024_08_21"` - - `"direct"` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `Program object { caller_id, type }` + - `"auto"` - - `caller_id: string` + - `"default_2024_08_21"` - The call ID of the program item that produced this tool call. + - `score_threshold: number` - - `type: "program"` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - The caller type. Always `program`. + - `results: optional array of object { file_id, file_name, score, content }` - - `"program"` + The results of the file search. - - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` + - `file_id: string` - The streamed output emitted by an apply patch tool call. + The ID of the file that result was found in. - - `call_id: string` + - `file_name: string` - The unique ID of the apply patch tool call generated by the model. + The name of the file that result was found in. - - `status: "completed" or "failed"` + - `score: number` - The status of the apply patch tool call output. One of `completed` or `failed`. + The score of the result. All values must be a floating point number between 0 and 1. - - `"completed"` + - `content: optional array of object { text, type }` - - `"failed"` + The content of the result that was found. The content is only included if requested via the include query parameter. - - `type: "apply_patch_call_output"` + - `text: optional string` - The type of the item. Always `apply_patch_call_output`. + The text content of the file. - - `"apply_patch_call_output"` + - `type: optional "text"` - - `id: optional string` + The type of the content. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `"text"` - - `agent: optional object { agent_name }` + - `type: "file_search"` - The agent that produced this item. + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `agent_name: string` + - `"file_search"` - The canonical name of the agent that produced this item. + - `FunctionToolCall object { id, function, type }` - - `caller: optional object { type } or object { caller_id, type }` + - `id: string` - The execution context that produced this tool call. + The ID of the tool call object. - - `Direct object { type }` + - `function: object { arguments, name, output }` - - `type: "direct"` + The definition of the function that was called. - The caller type. Always `direct`. + - `arguments: string` - - `"direct"` + The arguments passed to the function. - - `Program object { caller_id, type }` + - `name: string` - - `caller_id: string` + The name of the function. - The call ID of the program item that produced this tool call. + - `output: string` - - `type: "program"` + The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. - The caller type. Always `program`. + - `type: "function"` - - `"program"` + The type of tool call. This is always going to be `function` for this type of tool call. - - `output: optional string` + - `"function"` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `type: "tool_calls"` - - `McpListTools object { id, server_label, tools, 3 more }` + Always `tool_calls`. - A list of tools available on an MCP server. + - `"tool_calls"` - - `id: string` + - `thread_id: string` - The unique ID of the list. + The ID of the [thread](/docs/api-reference/threads) that was run. - - `server_label: string` + - `type: "message_creation" or "tool_calls"` - The label of the MCP server. + The type of run step, which can be either `message_creation` or `tool_calls`. - - `tools: array of object { input_schema, name, annotations, description }` + - `"message_creation"` - The tools available on the server. + - `"tool_calls"` - - `input_schema: unknown` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - The JSON schema describing the tool's input. + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - - `name: string` + - `completion_tokens: number` - The name of the tool. + Number of completion tokens used over the course of the run step. - - `annotations: optional unknown` + - `prompt_tokens: number` - Additional annotations about the tool. + Number of prompt tokens used over the course of the run step. - - `description: optional string` + - `total_tokens: number` - The description of the tool. + Total number of tokens used (prompt + completion). - - `type: "mcp_list_tools"` + - `event: "thread.run.step.created"` - The type of the item. Always `mcp_list_tools`. + - `"thread.run.step.created"` - - `"mcp_list_tools"` + - `ThreadRunStepInProgress object { data, event }` - - `agent: optional object { agent_name }` + Occurs when a [run step](/docs/api-reference/run-steps/step-object) moves to an `in_progress` state. - The agent that produced this item. + - `data: RunStep` - - `agent_name: string` + Represents a step in execution of a run. - The canonical name of the agent that produced this item. + - `event: "thread.run.step.in_progress"` - - `error: optional string` + - `"thread.run.step.in_progress"` - Error message if the server could not list tools. + - `ThreadRunStepDelta object { data, event }` - - `McpApprovalRequest object { id, arguments, name, 3 more }` + Occurs when parts of a [run step](/docs/api-reference/run-steps/step-object) are being streamed. - A request for human approval of a tool invocation. + - `data: RunStepDeltaEvent` + + Represents a run step delta i.e. any changed fields on a run step during streaming. - `id: string` - The unique ID of the approval request. + The identifier of the run step, which can be referenced in API endpoints. - - `arguments: string` + - `delta: object { step_details }` - A JSON string of arguments for the tool. + The delta containing the fields that have changed on the run step. - - `name: string` + - `step_details: optional RunStepDeltaMessageDelta or ToolCallDeltaObject` - The name of the tool to run. + The details of the run step. - - `server_label: string` + - `RunStepDeltaMessageDelta object { type, message_creation }` - The label of the MCP server making the request. + Details of the message creation by the run step. - - `type: "mcp_approval_request"` + - `type: "message_creation"` - The type of the item. Always `mcp_approval_request`. + Always `message_creation`. - - `"mcp_approval_request"` + - `"message_creation"` - - `agent: optional object { agent_name }` + - `message_creation: optional object { message_id }` - The agent that produced this item. + - `message_id: optional string` - - `agent_name: string` + The ID of the message that was created by this run step. - The canonical name of the agent that produced this item. + - `ToolCallDeltaObject object { type, tool_calls }` - - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` + Details of the tool call. - A response to an MCP approval request. + - `type: "tool_calls"` - - `approval_request_id: string` + Always `tool_calls`. - The ID of the approval request being answered. + - `"tool_calls"` - - `approve: boolean` + - `tool_calls: optional array of CodeInterpreterToolCallDelta or FileSearchToolCallDelta or FunctionToolCallDelta` - Whether the request was approved. + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - - `type: "mcp_approval_response"` + - `CodeInterpreterToolCallDelta object { index, type, id, code_interpreter }` - The type of the item. Always `mcp_approval_response`. + Details of the Code Interpreter tool call the run step was involved in. - - `"mcp_approval_response"` + - `index: number` - - `id: optional string` + The index of the tool call in the tool calls array. - The unique ID of the approval response + - `type: "code_interpreter"` - - `agent: optional object { agent_name }` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - The agent that produced this item. + - `"code_interpreter"` - - `agent_name: string` + - `id: optional string` - The canonical name of the agent that produced this item. + The ID of the tool call. - - `reason: optional string` + - `code_interpreter: optional object { input, outputs }` - Optional reason for the decision. + The Code Interpreter tool call definition. - - `McpCall object { id, arguments, name, 7 more }` + - `input: optional string` - An invocation of a tool on an MCP server. + The input to the Code Interpreter tool call. - - `id: string` + - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` - The unique ID of the tool call. + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `arguments: string` + - `CodeInterpreterLogs object { index, type, logs }` - A JSON string of the arguments passed to the tool. + Text output from the Code Interpreter tool call as part of a run step. - - `name: string` + - `index: number` - The name of the tool that was run. + The index of the output in the outputs array. - - `server_label: string` + - `type: "logs"` - The label of the MCP server running the tool. + Always `logs`. - - `type: "mcp_call"` + - `"logs"` - The type of the item. Always `mcp_call`. + - `logs: optional string` - - `"mcp_call"` + The text output from the Code Interpreter tool call. - - `agent: optional object { agent_name }` + - `CodeInterpreterOutputImage object { index, type, image }` - The agent that produced this item. + - `index: number` - - `agent_name: string` + The index of the output in the outputs array. - The canonical name of the agent that produced this item. + - `type: "image"` - - `approval_request_id: optional string` + Always `image`. - 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. + - `"image"` - - `error: optional string` + - `image: optional object { file_id }` - The error from the tool call, if any. + - `file_id: optional string` - - `output: optional string` + The [file](/docs/api-reference/files) ID of the image. - The output from the tool call. + - `FileSearchToolCallDelta object { file_search, index, type, id }` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `file_search: unknown` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + For now, this is always going to be an empty object. - - `"in_progress"` + - `index: number` - - `"completed"` + The index of the tool call in the tool calls array. - - `"incomplete"` + - `type: "file_search"` - - `"calling"` + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `"failed"` + - `"file_search"` - - `CustomToolCallOutput object { call_id, output, type, 3 more }` + - `id: optional string` - The output of a custom tool call from your code, being sent back to the model. + The ID of the tool call object. - - `call_id: string` + - `FunctionToolCallDelta object { index, type, id, function }` - The call ID, used to map this custom tool call output to a custom tool call. + - `index: number` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The index of the tool call in the tool calls array. - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `type: "function"` - - `StringOutput = string` + The type of tool call. This is always going to be `function` for this type of tool call. - A string of the output of the custom tool call. + - `"function"` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `id: optional string` - Text, image, or file output of the custom tool call. + The ID of the tool call object. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `function: optional object { arguments, name, output }` - A text input to the model. + The definition of the function that was called. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `arguments: optional string` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + The arguments passed to the function. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `name: optional string` - A file input to the model. + The name of the function. - - `type: "custom_tool_call_output"` + - `output: optional string` - The type of the custom tool call output. Always `custom_tool_call_output`. + The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. - - `"custom_tool_call_output"` + - `object: "thread.run.step.delta"` - - `id: optional string` + The object type, which is always `thread.run.step.delta`. - The unique ID of the custom tool call output in the OpenAI platform. + - `"thread.run.step.delta"` - - `agent: optional object { agent_name }` + - `event: "thread.run.step.delta"` - The agent that produced this item. + - `"thread.run.step.delta"` - - `agent_name: string` + - `ThreadRunStepCompleted object { data, event }` - The canonical name of the agent that produced this item. + Occurs when a [run step](/docs/api-reference/run-steps/step-object) is completed. - - `caller: optional object { type } or object { caller_id, type }` + - `data: RunStep` - The execution context that produced this tool call. + Represents a step in execution of a run. - - `Direct object { type }` + - `event: "thread.run.step.completed"` - - `type: "direct"` + - `"thread.run.step.completed"` - The caller type. Always `direct`. + - `ThreadRunStepFailed object { data, event }` - - `"direct"` + Occurs when a [run step](/docs/api-reference/run-steps/step-object) fails. - - `Program object { caller_id, type }` + - `data: RunStep` - - `caller_id: string` + Represents a step in execution of a run. - The call ID of the program item that produced this tool call. + - `event: "thread.run.step.failed"` - - `type: "program"` + - `"thread.run.step.failed"` - The caller type. Always `program`. + - `ThreadRunStepCancelled object { data, event }` - - `"program"` + Occurs when a [run step](/docs/api-reference/run-steps/step-object) is cancelled. - - `CustomToolCall object { call_id, input, name, 5 more }` + - `data: RunStep` - A call to a custom tool created by the model. + Represents a step in execution of a run. - - `call_id: string` + - `event: "thread.run.step.cancelled"` - An identifier used to map this custom tool call to a tool call output. + - `"thread.run.step.cancelled"` - - `input: string` + - `ThreadRunStepExpired object { data, event }` - The input for the custom tool call generated by the model. + Occurs when a [run step](/docs/api-reference/run-steps/step-object) expires. - - `name: string` + - `data: RunStep` - The name of the custom tool being called. + Represents a step in execution of a run. - - `type: "custom_tool_call"` + - `event: "thread.run.step.expired"` - The type of the custom tool call. Always `custom_tool_call`. + - `"thread.run.step.expired"` - - `"custom_tool_call"` +### Run Stream Event - - `id: optional string` +- `RunStreamEvent = object { data, event } or object { data, event } or object { data, event } or 7 more` - The unique ID of the custom tool call in the OpenAI platform. + Occurs when a new [run](/docs/api-reference/runs/object) is created. - - `agent: optional object { agent_name }` + - `ThreadRunCreated object { data, event }` - The agent that produced this item. + Occurs when a new [run](/docs/api-reference/runs/object) is created. - - `agent_name: string` + - `data: Run` - The canonical name of the agent that produced this item. + Represents an execution run on a [thread](/docs/api-reference/threads). - - `caller: optional object { type } or object { caller_id, type }` + - `id: string` - The execution context that produced this tool call. + The identifier, which can be referenced in API endpoints. - - `Direct object { type }` + - `assistant_id: string` - - `type: "direct"` + The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. - - `"direct"` + - `cancelled_at: number` - - `Program object { caller_id, type }` + The Unix timestamp (in seconds) for when the run was cancelled. - - `caller_id: string` + - `completed_at: number` - The call ID of the program item that produced this tool call. + The Unix timestamp (in seconds) for when the run was completed. - - `type: "program"` + - `created_at: number` - - `"program"` + The Unix timestamp (in seconds) for when the run was created. - - `namespace: optional string` + - `expires_at: number` - The namespace of the custom tool being called. + The Unix timestamp (in seconds) for when the run will expire. - - `CompactionTrigger object { type, agent }` + - `failed_at: number` - Compacts the current context. Must be the final input item. + The Unix timestamp (in seconds) for when the run failed. - - `type: "compaction_trigger"` + - `incomplete_details: object { reason }` - The type of the item. Always `compaction_trigger`. + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `"compaction_trigger"` + - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` - - `agent: optional object { agent_name }` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - The agent that produced this item. + - `"max_completion_tokens"` - - `agent_name: string` + - `"max_prompt_tokens"` - The canonical name of the agent that produced this item. + - `instructions: string` - - `ItemReference object { id, agent, type }` + The instructions that the [assistant](/docs/api-reference/assistants) used for this run. - An internal identifier for an item to reference. + - `last_error: object { code, message }` - - `id: string` + The last error associated with this run. Will be `null` if there are no errors. - The ID of the item to reference. + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` - - `agent: optional object { agent_name }` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - The agent that produced this item. + - `"server_error"` - - `agent_name: string` + - `"rate_limit_exceeded"` - The canonical name of the agent that produced this item. + - `"invalid_prompt"` - - `type: optional "item_reference"` + - `message: string` - The type of item to reference. Always `item_reference`. + A human-readable description of the error. - - `"item_reference"` + - `max_completion_tokens: number` - - `Program object { id, call_id, code, 3 more }` + The maximum number of completion tokens specified to have been used over the course of the run. - - `id: string` + - `max_prompt_tokens: number` - The unique ID of this program item. + The maximum number of prompt tokens specified to have been used over the course of the run. - - `call_id: string` + - `metadata: Metadata` - The stable call ID of the program 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. - - `code: string` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The JavaScript source executed by programmatic tool calling. + - `model: string` - - `fingerprint: string` + The model that the [assistant](/docs/api-reference/assistants) used for this run. - Opaque program replay fingerprint that must be round-tripped. + - `object: "thread.run"` - - `type: "program"` + The object type, which is always `thread.run`. - The item type. Always `program`. + - `"thread.run"` - - `"program"` + - `parallel_tool_calls: boolean` - - `agent: optional object { agent_name }` + Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - The agent that produced this item. + - `required_action: object { submit_tool_outputs, type }` - - `agent_name: string` + Details on the action required to continue the run. Will be `null` if no action is required. - The canonical name of the agent that produced this item. + - `submit_tool_outputs: object { tool_calls }` - - `ProgramOutput object { id, call_id, result, 3 more }` + Details on the tool outputs needed for this run to continue. - - `id: string` + - `tool_calls: array of RequiredActionFunctionToolCall` - The unique ID of this program output item. + A list of the relevant tool calls. - - `call_id: string` + - `id: string` - The call ID of the program item. + The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](/docs/api-reference/runs/submitToolOutputs) endpoint. - - `result: string` + - `function: object { arguments, name }` - The result produced by the program item. + The function definition. - - `status: "completed" or "incomplete"` + - `arguments: string` - The terminal status of the program output. + The arguments that the model expects you to pass to the function. - - `"completed"` + - `name: string` - - `"incomplete"` + The name of the function. - - `type: "program_output"` + - `type: "function"` - The item type. Always `program_output`. + The type of tool call the output is required for. For now, this is always `function`. - - `"program_output"` + - `"function"` - - `agent: optional object { agent_name }` + - `type: "submit_tool_outputs"` - The agent that produced this item. + For now, this is always `submit_tool_outputs`. - - `agent_name: string` + - `"submit_tool_outputs"` - The canonical name of the agent that produced this item. + - `response_format: AssistantResponseFormatOption` -- `instructions: optional string` + Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - A system (or developer) message inserted into the model's context. + Setting to `{ "type": "json_schema", "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). - 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. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. -- `max_output_tokens: optional number` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - 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). + - `"auto"` -- `max_tool_calls: optional number` + `auto` is the default value - 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. + - `"auto"` -- `metadata: optional map[string]` + - `ResponseFormatText object { 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. + Default response format. Used to generate text responses. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `type: "text"` -- `model: optional "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + The type of response format being defined. Always `text`. - 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. + - `"text"` - - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` + - `ResponseFormatJSONObject object { type }` - 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. + 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. - - `"gpt-5.6-sol"` + - `type: "json_object"` - - `"gpt-5.6-terra"` + The type of response format being defined. Always `json_object`. - - `"gpt-5.6-luna"` + - `"json_object"` - - `"gpt-5.4"` + - `ResponseFormatJSONSchema object { json_schema, type }` - - `"gpt-5.4-mini"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `"gpt-5.4-nano"` + - `json_schema: object { name, description, schema, strict }` - - `"gpt-5.4-mini-2026-03-17"` + Structured Outputs configuration options, including a JSON Schema. - - `"gpt-5.4-nano-2026-03-17"` + - `name: string` - - `"gpt-5.3-chat-latest"` + 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. - - `"gpt-5.2"` + - `description: optional string` - - `"gpt-5.2-2025-12-11"` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `"gpt-5.2-chat-latest"` + - `schema: optional map[unknown]` - - `"gpt-5.2-pro"` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `"gpt-5.2-pro-2025-12-11"` + - `strict: optional boolean` - - `"gpt-5.1"` + 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). - - `"gpt-5.1-2025-11-13"` + - `type: "json_schema"` - - `"gpt-5.1-codex"` + The type of response format being defined. Always `json_schema`. - - `"gpt-5.1-mini"` + - `"json_schema"` - - `"gpt-5.1-chat-latest"` + - `started_at: number` - - `"gpt-5"` + The Unix timestamp (in seconds) for when the run was started. - - `"gpt-5-mini"` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - - `"gpt-5-nano"` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `"gpt-5-2025-08-07"` + - `"queued"` - - `"gpt-5-mini-2025-08-07"` + - `"in_progress"` - - `"gpt-5-nano-2025-08-07"` + - `"requires_action"` - - `"gpt-5-chat-latest"` + - `"cancelling"` - - `"gpt-4.1"` + - `"cancelled"` - - `"gpt-4.1-mini"` + - `"failed"` - - `"gpt-4.1-nano"` + - `"completed"` - - `"gpt-4.1-2025-04-14"` + - `"incomplete"` - - `"gpt-4.1-mini-2025-04-14"` + - `"expired"` - - `"gpt-4.1-nano-2025-04-14"` + - `thread_id: string` - - `"o4-mini"` + The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. - - `"o4-mini-2025-04-16"` + - `tool_choice: AssistantToolChoiceOption` - - `"o3"` + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - - `"o3-2025-04-16"` + - `"none" or "auto" or "required"` - - `"o3-mini"` + `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. - - `"o3-mini-2025-01-31"` + - `"none"` - - `"o1"` + - `"auto"` - - `"o1-2024-12-17"` + - `"required"` - - `"o1-preview"` + - `AssistantToolChoice object { type, function }` - - `"o1-preview-2024-09-12"` + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `"o1-mini"` + - `type: "function" or "code_interpreter" or "file_search"` - - `"o1-mini-2024-09-12"` + The type of the tool. If type is `function`, the function name must be set - - `"gpt-4o"` + - `"function"` - - `"gpt-4o-2024-11-20"` + - `"code_interpreter"` - - `"gpt-4o-2024-08-06"` + - `"file_search"` - - `"gpt-4o-2024-05-13"` + - `function: optional AssistantToolChoiceFunction` - - `"gpt-4o-audio-preview"` + - `name: string` - - `"gpt-4o-audio-preview-2024-10-01"` + The name of the function to call. - - `"gpt-4o-audio-preview-2024-12-17"` + - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` - - `"gpt-4o-audio-preview-2025-06-03"` + The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. - - `"gpt-4o-mini-audio-preview"` + - `CodeInterpreterTool object { type }` - - `"gpt-4o-mini-audio-preview-2024-12-17"` + - `type: "code_interpreter"` - - `"gpt-4o-search-preview"` + The type of tool being defined: `code_interpreter` - - `"gpt-4o-mini-search-preview"` + - `"code_interpreter"` - - `"gpt-4o-search-preview-2025-03-11"` + - `FileSearchTool object { type, file_search }` - - `"gpt-4o-mini-search-preview-2025-03-11"` + - `type: "file_search"` - - `"chatgpt-4o-latest"` + The type of tool being defined: `file_search` - - `"codex-mini-latest"` + - `"file_search"` - - `"gpt-4o-mini"` + - `file_search: optional object { max_num_results, ranking_options }` - - `"gpt-4o-mini-2024-07-18"` + Overrides for the file search tool. - - `"gpt-4-turbo"` + - `max_num_results: optional number` - - `"gpt-4-turbo-2024-04-09"` + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `"gpt-4-0125-preview"` + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `"gpt-4-turbo-preview"` + - `ranking_options: optional object { score_threshold, ranker }` - - `"gpt-4-1106-preview"` + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - `"gpt-4-vision-preview"` + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `"gpt-4"` + - `score_threshold: number` - - `"gpt-4-0314"` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `"gpt-4-0613"` + - `ranker: optional "auto" or "default_2024_08_21"` - - `"gpt-4-32k"` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `"gpt-4-32k-0314"` + - `"auto"` - - `"gpt-4-32k-0613"` + - `"default_2024_08_21"` - - `"gpt-3.5-turbo"` + - `FunctionTool object { function, type }` - - `"gpt-3.5-turbo-16k"` + - `function: FunctionDefinition` - - `"gpt-3.5-turbo-0301"` + - `name: string` - - `"gpt-3.5-turbo-0613"` + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `"gpt-3.5-turbo-1106"` + - `description: optional string` - - `"gpt-3.5-turbo-0125"` + A description of what the function does, used by the model to choose when and how to call the function. - - `"gpt-3.5-turbo-16k-0613"` + - `parameters: optional FunctionParameters` - - `"o1-pro"` + The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - `"o1-pro-2025-03-19"` + Omitting `parameters` defines a function with an empty parameter list. - - `"o3-pro"` + - `strict: optional boolean` - - `"o3-pro-2025-06-10"` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-calling). - - `"o3-deep-research"` + - `type: "function"` - - `"o3-deep-research-2025-06-26"` + The type of tool being defined: `function` - - `"o4-mini-deep-research"` + - `"function"` - - `"o4-mini-deep-research-2025-06-26"` + - `truncation_strategy: object { type, last_messages }` - - `"computer-use-preview"` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `"computer-use-preview-2025-03-11"` + - `type: "auto" or "last_messages"` - - `"gpt-5-codex"` + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. - - `"gpt-5-pro"` + - `"auto"` - - `"gpt-5-pro-2025-10-06"` + - `"last_messages"` - - `"gpt-5.1-codex-max"` + - `last_messages: optional number` - - `string` + The number of most recent messages from the thread when constructing the context for the run. -- `moderation: optional object { model, policy }` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - Configuration for running moderation on the input and output of this response. + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - - `model: string` + - `completion_tokens: number` - The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'. + Number of completion tokens used over the course of the run. - - `policy: optional object { input, output }` + - `prompt_tokens: number` - The policy to apply to moderated response input and output. + Number of prompt tokens used over the course of the run. - - `input: optional object { mode }` + - `total_tokens: number` - The moderation policy for the response input. + Total number of tokens used (prompt + completion). - - `mode: "score" or "block"` + - `temperature: optional number` - - `"score"` + The sampling temperature used for this run. If not set, defaults to 1. - - `"block"` + - `top_p: optional number` - - `output: optional object { mode }` + The nucleus sampling value used for this run. If not set, defaults to 1. - The moderation policy for the response output. + - `event: "thread.run.created"` - - `mode: "score" or "block"` + - `"thread.run.created"` - - `"score"` + - `ThreadRunQueued object { data, event }` - - `"block"` + Occurs when a [run](/docs/api-reference/runs/object) moves to a `queued` status. -- `multi_agent: optional object { enabled, max_concurrent_subagents }` + - `data: Run` - Configuration for server-hosted multi-agent execution. + Represents an execution run on a [thread](/docs/api-reference/threads). - - `enabled: boolean` + - `event: "thread.run.queued"` - Whether to enable server-hosted multi-agent execution for this response. + - `"thread.run.queued"` - - `max_concurrent_subagents: optional number` + - `ThreadRunInProgress object { data, event }` - `max_concurrent_subagents` sets the maximum number of subagents that can be active simultaneously across the entire agent tree. It includes all descendants—children, grandchildren, and deeper subagents—but excludes the root agent. - The API does not impose a fixed upper bound on this setting. The default is `3`, which is recommended for most workloads. Multi-agent runs also have no fixed limit on tree depth or the total number of subagents created during a run. + Occurs when a [run](/docs/api-reference/runs/object) moves to an `in_progress` status. -- `parallel_tool_calls: optional boolean` + - `data: Run` - Whether to allow the model to run tool calls in parallel. + Represents an execution run on a [thread](/docs/api-reference/threads). -- `previous_response_id: optional string` + - `event: "thread.run.in_progress"` - 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`. + - `"thread.run.in_progress"` -- `prompt: optional BetaResponsePrompt` + - `ThreadRunRequiresAction object { data, event }` - Reference to a prompt template and its variables. - [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). + Occurs when a [run](/docs/api-reference/runs/object) moves to a `requires_action` status. - - `id: string` + - `data: Run` - The unique identifier of the prompt template to use. + Represents an execution run on a [thread](/docs/api-reference/threads). - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + - `event: "thread.run.requires_action"` - 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. + - `"thread.run.requires_action"` - - `string` + - `ThreadRunCompleted object { data, event }` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + Occurs when a [run](/docs/api-reference/runs/object) is completed. - A text input to the model. + - `data: Run` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + Represents an execution run on a [thread](/docs/api-reference/threads). - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `event: "thread.run.completed"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `"thread.run.completed"` - A file input to the model. + - `ThreadRunIncomplete object { data, event }` - - `version: optional string` + Occurs when a [run](/docs/api-reference/runs/object) ends with status `incomplete`. - Optional version of the prompt template. + - `data: Run` -- `prompt_cache_key: optional string` + Represents an execution run on a [thread](/docs/api-reference/threads). - 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). + - `event: "thread.run.incomplete"` -- `prompt_cache_options: optional object { mode, ttl }` + - `"thread.run.incomplete"` - 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. + - `ThreadRunFailed object { data, event }` - - `mode: optional "implicit" or "explicit"` + Occurs when a [run](/docs/api-reference/runs/object) fails. - 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. + - `data: Run` - - `"implicit"` + Represents an execution run on a [thread](/docs/api-reference/threads). - - `"explicit"` + - `event: "thread.run.failed"` - - `ttl: optional "30m"` + - `"thread.run.failed"` - 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. + - `ThreadRunCancelling object { data, event }` - - `"30m"` + Occurs when a [run](/docs/api-reference/runs/object) moves to a `cancelling` status. -- `prompt_cache_retention: optional "in_memory" or "24h"` + - `data: Run` - Deprecated. Use `prompt_cache_options.ttl` instead. + Represents an execution run on a [thread](/docs/api-reference/threads). - 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. + - `event: "thread.run.cancelling"` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `"thread.run.cancelling"` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `ThreadRunCancelled object { data, event }` - - `"in_memory"` + Occurs when a [run](/docs/api-reference/runs/object) is cancelled. - - `"24h"` + - `data: Run` -- `reasoning: optional object { context, effort, generate_summary, 2 more }` + Represents an execution run on a [thread](/docs/api-reference/threads). - **gpt-5 and o-series models only** + - `event: "thread.run.cancelled"` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `"thread.run.cancelled"` - - `context: optional "auto" or "current_turn" or "all_turns"` + - `ThreadRunExpired object { data, event }` - 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`. + Occurs when a [run](/docs/api-reference/runs/object) expires. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `data: Run` - - `"auto"` + Represents an execution run on a [thread](/docs/api-reference/threads). - - `"current_turn"` + - `event: "thread.run.expired"` - - `"all_turns"` + - `"thread.run.expired"` - - `effort: optional "none" or "minimal" or "low" or 4 more` +### Thread Stream Event - 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. +- `ThreadStreamEvent object { data, event, enabled }` - - `"none"` + Occurs when a new [thread](/docs/api-reference/threads/object) is created. - - `"minimal"` + - `data: Thread` - - `"low"` + Represents a thread that contains [messages](/docs/api-reference/messages). - - `"medium"` + - `id: string` - - `"high"` + The identifier, which can be referenced in API endpoints. - - `"xhigh"` + - `created_at: number` - - `"max"` + The Unix timestamp (in seconds) for when the thread was created. - - `generate_summary: optional "auto" or "concise" or "detailed"` + - `metadata: Metadata` - **Deprecated:** use `summary` instead. + 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. - 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`. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"auto"` + - `object: "thread"` - - `"concise"` + The object type, which is always `thread`. - - `"detailed"` + - `"thread"` - - `mode: optional string or "standard" or "pro"` + - `tool_resources: object { code_interpreter, file_search }` - Controls the reasoning execution mode for the request. + A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. - When returned on a response, this is the effective execution mode. + - `code_interpreter: optional object { file_ids }` - - `string` + - `file_ids: optional array of string` - - `"standard" or "pro"` + A list of [file](/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. - Controls the reasoning execution mode for the request. + - `file_search: optional object { vector_store_ids }` - When returned on a response, this is the effective execution mode. + - `vector_store_ids: optional array of string` - - `"standard"` + The [vector store](/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. - - `"pro"` + - `event: "thread.created"` - - `summary: optional "auto" or "concise" or "detailed"` + - `"thread.created"` - 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`. + - `enabled: optional boolean` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + Whether to enable input audio transcription. - - `"auto"` +# ChatKit - - `"concise"` +## Domain Types - - `"detailed"` +### ChatKit Workflow -- `safety_identifier: optional string` +- `ChatKitWorkflow object { id, state_variables, tracing, version }` - 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). + Workflow metadata and state returned for the session. -- `service_tier: optional "auto" or "default" or "flex" or 2 more` + - `id: string` - Specifies the processing type used for serving the request. + Identifier of the workflow backing the session. - - 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'. + - `state_variables: map[string or boolean or number]` - 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. + State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. - - `"auto"` + - `string` - - `"default"` + - `boolean` - - `"flex"` + - `number` - - `"scale"` + - `tracing: object { enabled }` - - `"priority"` + Tracing settings applied to the workflow. -- `store: optional boolean` + - `enabled: boolean` - Whether to store the generated model response for later retrieval via - API. + Indicates whether tracing is enabled. -- `stream: optional boolean` + - `version: string` - 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. + Specific workflow version used for the session. Defaults to null when using the latest deployment. -- `stream_options: optional object { include_obfuscation }` +# Sessions - Options for streaming responses. Only set this when you set `stream: true`. +## Cancel chat session - - `include_obfuscation: optional boolean` +**post** `/chatkit/sessions/{session_id}/cancel` - 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. +Cancel an active ChatKit session and return its most recent metadata. -- `temperature: optional number` +Cancelling prevents new requests from using the issued client secret. - 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. +### Path Parameters -- `text: optional BetaResponseTextConfig` +- `session_id: string` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: +### Returns - - [Text inputs and outputs](/docs/guides/text) - - [Structured Outputs](/docs/guides/structured-outputs) +- `ChatSession object { id, chatkit_configuration, client_secret, 7 more }` - - `format: optional BetaResponseFormatTextConfig` + Represents a ChatKit session and its resolved configuration. - An object specifying the format that the model must output. + - `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). + Identifier for the ChatKit session. - The default format is `{ "type": "text" }` with no additional options. + - `chatkit_configuration: ChatSessionChatKitConfiguration` - **Not recommended for gpt-4o and newer models:** + Resolved ChatKit feature configuration for the session. - 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. + - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` - - `Text object { type }` + Automatic thread titling preferences. - Default response format. Used to generate text responses. + - `enabled: boolean` - - `type: "text"` + Whether automatic thread titling is enabled. - The type of response format being defined. Always `text`. + - `file_upload: ChatSessionFileUpload` - - `"text"` + Upload settings for the session. - - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` + - `enabled: boolean` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + Indicates if uploads are enabled for the session. - - `name: string` + - `max_file_size: number` - 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. + Maximum upload size in megabytes. - - `schema: map[unknown]` + - `max_files: number` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + Maximum number of uploads allowed during the session. - - `type: "json_schema"` + - `history: ChatSessionHistory` - The type of response format being defined. Always `json_schema`. + History retention configuration. - - `"json_schema"` + - `enabled: boolean` - - `description: optional string` + Indicates if chat history is persisted for the session. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `recent_threads: number` - - `strict: optional boolean` + Number of prior threads surfaced in history views. Defaults to null when all history is retained. - 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). + - `client_secret: string` - - `JSONObject object { type }` + Ephemeral client secret that authenticates session requests. - 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. + - `expires_at: number` - - `type: "json_object"` + Unix timestamp (in seconds) for when the session expires. - The type of response format being defined. Always `json_object`. + - `max_requests_per_1_minute: number` - - `"json_object"` + Convenience copy of the per-minute request limit. - - `verbosity: optional "low" or "medium" or "high"` + - `object: "chatkit.session"` - 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`. + Type discriminator that is always `chatkit.session`. - - `"low"` + - `"chatkit.session"` - - `"medium"` + - `rate_limits: ChatSessionRateLimits` - - `"high"` + Resolved rate limit values. -- `tool_choice: optional BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + - `max_requests_per_1_minute: number` - 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. + Maximum allowed requests per one-minute window. - - `BetaToolChoiceOptions = "none" or "auto" or "required"` + - `status: ChatSessionStatus` - Controls which (if any) tool is called by the model. + Current lifecycle state of the session. - `none` means the model will not call any tool and instead generates a message. + - `"active"` - `auto` means the model can pick between generating a message or calling one or - more tools. + - `"expired"` - `required` means the model must call one or more tools. + - `"cancelled"` - - `"none"` + - `user: string` - - `"auto"` + User identifier associated with the session. - - `"required"` + - `workflow: ChatKitWorkflow` - - `BetaToolChoiceAllowed object { mode, tools, type }` + Workflow metadata for the session. - Constrains the tools available to the model to a pre-defined set. + - `id: string` - - `mode: "auto" or "required"` + Identifier of the workflow backing the session. - Constrains the tools available to the model to a pre-defined set. + - `state_variables: map[string or boolean or number]` - `auto` allows the model to pick from among the allowed tools and generate a - message. + State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. - `required` requires the model to call one or more of the allowed tools. + - `string` - - `"auto"` + - `boolean` - - `"required"` + - `number` - - `tools: array of map[unknown]` + - `tracing: object { enabled }` - A list of tool definitions that the model should be allowed to call. + Tracing settings applied to the workflow. - For the Responses API, the list of tool definitions might look like: + - `enabled: boolean` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + Indicates whether tracing is enabled. - - `type: "allowed_tools"` + - `version: string` - Allowed tool configuration type. Always `allowed_tools`. + Specific workflow version used for the session. Defaults to null when using the latest deployment. - - `"allowed_tools"` +### Example - - `BetaToolChoiceTypes object { type }` +```http +curl https://api.openai.com/v1/chatkit/sessions/$SESSION_ID/cancel \ + -X POST \ + -H 'OpenAI-Beta: chatkit_beta=v1' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](/docs/guides/tools). +#### Response - - `type: "file_search" or "web_search_preview" or "computer" or 5 more` +```json +{ + "id": "id", + "chatkit_configuration": { + "automatic_thread_titling": { + "enabled": true + }, + "file_upload": { + "enabled": true, + "max_file_size": 0, + "max_files": 0 + }, + "history": { + "enabled": true, + "recent_threads": 0 + } + }, + "client_secret": "client_secret", + "expires_at": 0, + "max_requests_per_1_minute": 0, + "object": "chatkit.session", + "rate_limits": { + "max_requests_per_1_minute": 0 + }, + "status": "active", + "user": "user", + "workflow": { + "id": "id", + "state_variables": { + "foo": "string" + }, + "tracing": { + "enabled": true + }, + "version": "version" + } +} +``` - The type of hosted tool the model should to use. Learn more about - [built-in tools](/docs/guides/tools). +### Example - Allowed values are: +```http +curl -X POST \ + https://api.openai.com/v1/chatkit/sessions/cksess_123/cancel \ + -H "OpenAI-Beta: chatkit_beta=v1" \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` +#### Response - - `"file_search"` +```json +{ + "id": "cksess_123", + "object": "chatkit.session", + "workflow": { + "id": "workflow_alpha", + "version": "1" + }, + "scope": { + "customer_id": "cust_456" + }, + "max_requests_per_1_minute": 30, + "ttl_seconds": 900, + "status": "cancelled", + "cancelled_at": 1712345678 +} +``` - - `"web_search_preview"` +## Create ChatKit session - - `"computer"` +**post** `/chatkit/sessions` - - `"computer_use_preview"` +Create a ChatKit session. - - `"computer_use"` +### Body Parameters - - `"web_search_preview_2025_03_11"` +- `user: string` - - `"image_generation"` + A free-form string that identifies your end user; ensures this Session can access other objects that have the same `user` scope. - - `"code_interpreter"` +- `workflow: ChatSessionWorkflowParam` - - `BetaToolChoiceFunction object { name, type }` + Workflow that powers the session. - Use this option to force the model to call a specific function. + - `id: string` - - `name: string` + Identifier for the workflow invoked by the session. - The name of the function to call. - - - `type: "function"` + - `state_variables: optional map[string or boolean or number]` - For function calling, the type is always `function`. + State variables forwarded to the workflow. Keys may be up to 64 characters, values must be primitive types, and the map defaults to an empty object. - - `"function"` + - `string` - - `BetaToolChoiceMcp object { server_label, type, name }` + - `boolean` - Use this option to force the model to call a specific tool on a remote MCP server. + - `number` - - `server_label: string` + - `tracing: optional object { enabled }` - The label of the MCP server to use. + Optional tracing overrides for the workflow invocation. When omitted, tracing is enabled by default. - - `type: "mcp"` + - `enabled: optional boolean` - For MCP tools, the type is always `mcp`. + Whether tracing is enabled during the session. Defaults to true. - - `"mcp"` + - `version: optional string` - - `name: optional string` + Specific workflow version to run. Defaults to the latest deployed version. - The name of the tool to call on the server. +- `chatkit_configuration: optional ChatSessionChatKitConfigurationParam` - - `BetaToolChoiceCustom object { name, type }` + Optional overrides for ChatKit runtime configuration features - Use this option to force the model to call a specific custom tool. + - `automatic_thread_titling: optional object { enabled }` - - `name: string` + Configuration for automatic thread titling. When omitted, automatic thread titling is enabled by default. - The name of the custom tool to call. + - `enabled: optional boolean` - - `type: "custom"` + Enable automatic thread title generation. Defaults to true. - For custom tool calling, the type is always `custom`. + - `file_upload: optional object { enabled, max_file_size, max_files }` - - `"custom"` + Configuration for upload enablement and limits. When omitted, uploads are disabled by default (max_files 10, max_file_size 512 MB). - - `BetaSpecificProgrammaticToolCallingParam object { type }` + - `enabled: optional boolean` - - `type: "programmatic_tool_calling"` + Enable uploads for this session. Defaults to false. - The tool to call. Always `programmatic_tool_calling`. + - `max_file_size: optional number` - - `"programmatic_tool_calling"` + Maximum size in megabytes for each uploaded file. Defaults to 512 MB, which is the maximum allowable size. - - `BetaToolChoiceApplyPatch object { type }` + - `max_files: optional number` - Forces the model to call the apply_patch tool when executing a tool call. + Maximum number of files that can be uploaded to the session. Defaults to 10. - - `type: "apply_patch"` + - `history: optional object { enabled, recent_threads }` - The tool to call. Always `apply_patch`. + Configuration for chat history retention. When omitted, history is enabled by default with no limit on recent_threads (null). - - `"apply_patch"` + - `enabled: optional boolean` - - `BetaToolChoiceShell object { type }` + Enables chat users to access previous ChatKit threads. Defaults to true. - Forces the model to call the shell tool when a tool call is required. + - `recent_threads: optional number` - - `type: "shell"` + Number of recent ChatKit threads users have access to. Defaults to unlimited when unset. - The tool to call. Always `shell`. +- `expires_after: optional ChatSessionExpiresAfterParam` - - `"shell"` + Optional override for session expiration timing in seconds from creation. Defaults to 10 minutes. -- `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` + - `anchor: "created_at"` - 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. + Base timestamp used to calculate expiration. Currently fixed to `created_at`. - We support the following categories of tools: + - `"created_at"` - - **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. + - `seconds: number` - - `Function object { name, parameters, strict, 5 more }` + Number of seconds after the anchor when the session expires. - 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_limits: optional ChatSessionRateLimitsParam` - - `name: string` + Optional override for per-minute request limits. When omitted, defaults to 10. - The name of the function to call. + - `max_requests_per_1_minute: optional number` - - `parameters: map[unknown]` + Maximum number of requests allowed per minute for the session. Defaults to 10. - A JSON schema object describing the parameters of the function. +### Returns - - `strict: boolean` +- `ChatSession object { id, chatkit_configuration, client_secret, 7 more }` - Whether strict parameter validation is enforced for this function tool. + Represents a ChatKit session and its resolved configuration. - - `type: "function"` + - `id: string` - The type of the function tool. Always `function`. + Identifier for the ChatKit session. - - `"function"` + - `chatkit_configuration: ChatSessionChatKitConfiguration` - - `allowed_callers: optional array of "direct" or "programmatic"` + Resolved ChatKit feature configuration for the session. - The tool invocation context(s). + - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` - - `"direct"` + Automatic thread titling preferences. - - `"programmatic"` + - `enabled: boolean` - - `defer_loading: optional boolean` + Whether automatic thread titling is enabled. - Whether this function is deferred and loaded via tool search. + - `file_upload: ChatSessionFileUpload` - - `description: optional string` + Upload settings for the session. - A description of the function. Used by the model to determine whether or not to call the function. + - `enabled: boolean` - - `output_schema: optional map[unknown]` + Indicates if uploads are enabled for the session. - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `max_file_size: number` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + Maximum upload size in megabytes. - 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). + - `max_files: number` - - `type: "file_search"` + Maximum number of uploads allowed during the session. - The type of the file search tool. Always `file_search`. + - `history: ChatSessionHistory` - - `"file_search"` + History retention configuration. - - `vector_store_ids: array of string` + - `enabled: boolean` - The IDs of the vector stores to search. + Indicates if chat history is persisted for the session. - - `filters: optional object { key, type, value } or object { filters, type }` + - `recent_threads: number` - A filter to apply. + Number of prior threads surfaced in history views. Defaults to null when all history is retained. - - `ComparisonFilter object { key, type, value }` + - `client_secret: string` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + Ephemeral client secret that authenticates session requests. - - `key: string` + - `expires_at: number` - The key to compare against the value. + Unix timestamp (in seconds) for when the session expires. - - `type: "eq" or "ne" or "gt" or 5 more` + - `max_requests_per_1_minute: number` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + Convenience copy of the per-minute request limit. - - `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 + - `object: "chatkit.session"` - - `"eq"` + Type discriminator that is always `chatkit.session`. - - `"ne"` + - `"chatkit.session"` - - `"gt"` + - `rate_limits: ChatSessionRateLimits` - - `"gte"` + Resolved rate limit values. - - `"lt"` + - `max_requests_per_1_minute: number` - - `"lte"` + Maximum allowed requests per one-minute window. - - `"in"` + - `status: ChatSessionStatus` - - `"nin"` + Current lifecycle state of the session. - - `value: string or number or boolean or array of string or number` + - `"active"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `"expired"` - - `string` + - `"cancelled"` - - `number` + - `user: string` - - `boolean` + User identifier associated with the session. - - `array of string or number` + - `workflow: ChatKitWorkflow` - - `string` + Workflow metadata for the session. - - `number` + - `id: string` - - `CompoundFilter object { filters, type }` + Identifier of the workflow backing the session. - Combine multiple filters using `and` or `or`. + - `state_variables: map[string or boolean or number]` - - `filters: array of object { key, type, value } or unknown` + State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `string` - - `ComparisonFilter object { key, type, value }` + - `boolean` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `number` - - `key: string` + - `tracing: object { enabled }` - The key to compare against the value. + Tracing settings applied to the workflow. - - `type: "eq" or "ne" or "gt" or 5 more` + - `enabled: boolean` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + Indicates whether tracing is enabled. - - `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 + - `version: string` - - `"eq"` + Specific workflow version used for the session. Defaults to null when using the latest deployment. - - `"ne"` +### Example - - `"gt"` +```http +curl https://api.openai.com/v1/chatkit/sessions \ + -H 'Content-Type: application/json' \ + -H 'OpenAI-Beta: chatkit_beta=v1' \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "user": "x", + "workflow": { + "id": "id" + } + }' +``` - - `"gte"` +#### Response - - `"lt"` +```json +{ + "id": "id", + "chatkit_configuration": { + "automatic_thread_titling": { + "enabled": true + }, + "file_upload": { + "enabled": true, + "max_file_size": 0, + "max_files": 0 + }, + "history": { + "enabled": true, + "recent_threads": 0 + } + }, + "client_secret": "client_secret", + "expires_at": 0, + "max_requests_per_1_minute": 0, + "object": "chatkit.session", + "rate_limits": { + "max_requests_per_1_minute": 0 + }, + "status": "active", + "user": "user", + "workflow": { + "id": "id", + "state_variables": { + "foo": "string" + }, + "tracing": { + "enabled": true + }, + "version": "version" + } +} +``` - - `"lte"` +### Example - - `"in"` +```http +curl https://api.openai.com/v1/chatkit/sessions \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: chatkit_beta=v1" \ + -d '{ + "workflow": { + "id": "workflow_alpha", + "version": "2024-10-01" + }, + "scope": { + "project": "alpha", + "environment": "staging" + }, + "expires_after": 1800, + "max_requests_per_1_minute": 60, + "max_requests_per_session": 500 + }' +``` - - `"nin"` +#### Response - - `value: string or number or boolean or array of string or number` +```json +{ + "client_secret": "chatkit_token_123", + "expires_at": 1735689600, + "workflow": { + "id": "workflow_alpha", + "version": "2024-10-01" + }, + "scope": { + "project": "alpha", + "environment": "staging" + }, + "max_requests_per_1_minute": 60, + "max_requests_per_session": 500, + "status": "active" +} +``` - The value to compare against the attribute key; supports string, number, or boolean types. +# Threads - - `string` +## Delete ChatKit thread - - `number` +**delete** `/chatkit/threads/{thread_id}` - - `boolean` +Delete a ChatKit thread along with its items and stored attachments. - - `array of string or number` +### Path Parameters - - `string` +- `thread_id: string` - - `number` +### Returns - - `unknown` +- `id: string` - - `type: "and" or "or"` + Identifier of the deleted thread. - Type of operation: `and` or `or`. +- `deleted: boolean` - - `"and"` + Indicates that the thread has been deleted. - - `"or"` +- `object: "chatkit.thread.deleted"` - - `max_num_results: optional number` + Type discriminator that is always `chatkit.thread.deleted`. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `"chatkit.thread.deleted"` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` +### Example - Ranking options for search. +```http +curl https://api.openai.com/v1/chatkit/threads/$THREAD_ID \ + -X DELETE \ + -H 'OpenAI-Beta: chatkit_beta=v1' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `hybrid_search: optional object { embedding_weight, text_weight }` +#### Response - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. +```json +{ + "id": "id", + "deleted": true, + "object": "chatkit.thread.deleted" +} +``` - - `embedding_weight: number` +## List ChatKit threads - The weight of the embedding in the reciprocal ranking fusion. +**get** `/chatkit/threads` - - `text_weight: number` +List ChatKit threads with optional pagination and user filters. - The weight of the text in the reciprocal ranking fusion. +### Query Parameters - - `ranker: optional "auto" or "default-2024-11-15"` +- `after: optional string` - The ranker to use for the file search. + List items created after this thread item ID. Defaults to null for the first page. - - `"auto"` +- `before: optional string` - - `"default-2024-11-15"` + List items created before this thread item ID. Defaults to null for the newest results. - - `score_threshold: optional number` +- `limit: optional number` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + Maximum number of thread items to return. Defaults to 20. - - `Computer object { type }` +- `order: optional "asc" or "desc"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + Sort order for results by creation time. Defaults to `desc`. - - `type: "computer"` + - `"asc"` - The type of the computer tool. Always `computer`. + - `"desc"` - - `"computer"` +- `user: optional string` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + Filter threads that belong to this user identifier. Defaults to null to return all users. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). +### Returns - - `display_height: number` +- `data: array of ChatKitThread` - The height of the computer display. + A list of items - - `display_width: number` + - `id: string` - The width of the computer display. + Identifier of the thread. - - `environment: "windows" or "mac" or "linux" or 2 more` + - `created_at: number` - The type of computer environment to control. + Unix timestamp (in seconds) for when the thread was created. - - `"windows"` + - `object: "chatkit.thread"` - - `"mac"` + Type discriminator that is always `chatkit.thread`. - - `"linux"` + - `"chatkit.thread"` - - `"ubuntu"` + - `status: object { type } or object { reason, type } or object { reason, type }` - - `"browser"` + Current status for the thread. Defaults to `active` for newly created threads. - - `type: "computer_use_preview"` + - `Active object { type }` - The type of the computer use tool. Always `computer_use_preview`. + Indicates that a thread is active. - - `"computer_use_preview"` + - `type: "active"` - - `WebSearch object { type, filters, search_context_size, user_location }` + Status discriminator that is always `active`. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + - `"active"` - - `type: "web_search" or "web_search_2025_08_26"` + - `Locked object { reason, type }` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + Indicates that a thread is locked and cannot accept new input. - - `"web_search"` + - `reason: string` - - `"web_search_2025_08_26"` + Reason that the thread was locked. Defaults to null when no reason is recorded. - - `filters: optional object { allowed_domains }` + - `type: "locked"` - Filters for the search. + Status discriminator that is always `locked`. - - `allowed_domains: optional array of string` + - `"locked"` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `Closed object { reason, type }` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + Indicates that a thread has been closed. - - `search_context_size: optional "low" or "medium" or "high"` + - `reason: 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. + Reason that the thread was closed. Defaults to null when no reason is recorded. - - `"low"` + - `type: "closed"` - - `"medium"` + Status discriminator that is always `closed`. - - `"high"` + - `"closed"` - - `user_location: optional object { city, country, region, 2 more }` + - `title: string` - The approximate location of the user. + Optional human-readable title for the thread. Defaults to null when no title has been generated. - - `city: optional string` + - `user: string` - Free text input for the city of the user, e.g. `San Francisco`. + Free-form string that identifies your end user who owns the thread. - - `country: optional string` +- `first_id: 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 first item in the list. - - `region: optional string` +- `has_more: boolean` - Free text input for the region of the user, e.g. `California`. + Whether there are more items available. - - `timezone: optional string` +- `last_id: string` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The ID of the last item in the list. - - `type: optional "approximate"` +- `object: "list"` - The type of location approximation. Always `approximate`. + The type of object returned, must be `list`. - - `"approximate"` + - `"list"` - - `Mcp object { server_label, type, allowed_callers, 9 more }` +### Example - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). +```http +curl https://api.openai.com/v1/chatkit/threads \ + -H 'OpenAI-Beta: chatkit_beta=v1' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `server_label: string` +#### Response - A label for this MCP server, used to identify it in tool calls. +```json +{ + "data": [ + { + "id": "cthr_def456", + "created_at": 1712345600, + "object": "chatkit.thread", + "status": { + "type": "active" + }, + "title": "Demo feedback", + "user": "user_456" + } + ], + "first_id": "first_id", + "has_more": true, + "last_id": "last_id", + "object": "list" +} +``` - - `type: "mcp"` +### Example - The type of the MCP tool. Always `mcp`. +```http +curl "https://api.openai.com/v1/chatkit/threads?limit=2&order=desc" \ + -H "OpenAI-Beta: chatkit_beta=v1" \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `"mcp"` +#### Response - - `allowed_callers: optional array of "direct" or "programmatic"` +```json +{ + "data": [ + { + "id": "cthr_abc123", + "object": "chatkit.thread", + "title": "Customer escalation" + }, + { + "id": "cthr_def456", + "object": "chatkit.thread", + "title": "Demo feedback" + } + ], + "has_more": false, + "object": "list" +} +``` - The tool invocation context(s). +## List ChatKit thread items - - `"direct"` +**get** `/chatkit/threads/{thread_id}/items` - - `"programmatic"` +List items that belong to a ChatKit thread. - - `allowed_tools: optional array of string or object { read_only, tool_names }` +### Path Parameters - List of allowed tool names or a filter object. +- `thread_id: string` - - `McpAllowedTools = array of string` +### Query Parameters - A string array of allowed tool names +- `after: optional string` - - `McpToolFilter object { read_only, tool_names }` + List items created after this thread item ID. Defaults to null for the first page. - A filter object to specify which tools are allowed. +- `before: optional string` - - `read_only: optional boolean` + List items created before this thread item ID. Defaults to null for the newest results. - 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. +- `limit: optional number` - - `tool_names: optional array of string` + Maximum number of thread items to return. Defaults to 20. - List of allowed tool names. +- `order: optional "asc" or "desc"` - - `authorization: optional string` + Sort order for results by creation time. Defaults to `desc`. - 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. + - `"asc"` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `"desc"` - 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). +### Returns - Currently supported `connector_id` values are: +- `ChatKitThreadItemList object { data, first_id, has_more, 2 more }` - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + A paginated list of thread items rendered for the ChatKit API. - - `"connector_dropbox"` + - `data: array of ChatKitThreadUserMessageItem or ChatKitThreadAssistantMessageItem or ChatKitWidgetItem or 3 more` - - `"connector_gmail"` + A list of items - - `"connector_googlecalendar"` + - `ChatKitThreadUserMessageItem object { id, attachments, content, 5 more }` - - `"connector_googledrive"` + User-authored messages within a thread. - - `"connector_microsoftteams"` + - `id: string` - - `"connector_outlookcalendar"` + Identifier of the thread item. - - `"connector_outlookemail"` + - `attachments: array of ChatKitAttachment` - - `"connector_sharepoint"` + Attachments associated with the user message. Defaults to an empty list. - - `defer_loading: optional boolean` + - `id: string` - Whether this MCP tool is deferred and discovered via tool search. + Identifier for the attachment. - - `headers: optional map[string]` + - `mime_type: string` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + MIME type of the attachment. - - `require_approval: optional object { always, never } or "always" or "never"` + - `name: string` - Specify which of the MCP server's tools require approval. + Original display name for the attachment. - - `McpToolApprovalFilter object { always, never }` + - `preview_url: 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. + Preview URL for rendering the attachment inline. - - `always: optional object { read_only, tool_names }` + - `type: "image" or "file"` - A filter object to specify which tools are allowed. + Attachment discriminator. - - `read_only: optional boolean` + - `"image"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `"file"` - - `tool_names: optional array of string` + - `content: array of object { text, type } or object { text, type }` - List of allowed tool names. + Ordered content elements supplied by the user. - - `never: optional object { read_only, tool_names }` + - `InputText object { text, type }` - A filter object to specify which tools are allowed. + Text block that a user contributed to the thread. - - `read_only: optional boolean` + - `text: 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. + Plain-text content supplied by the user. - - `tool_names: optional array of string` + - `type: "input_text"` - List of allowed tool names. + Type discriminator that is always `input_text`. - - `McpToolApprovalSetting = "always" or "never"` + - `"input_text"` - 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. + - `QuotedText object { text, type }` - - `"always"` + Quoted snippet that the user referenced in their message. - - `"never"` + - `text: string` - - `server_description: optional string` + Quoted text content. - Optional description of the MCP server, used to provide more context. + - `type: "quoted_text"` - - `server_url: optional string` + Type discriminator that is always `quoted_text`. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `"quoted_text"` - - `tunnel_id: optional string` + - `created_at: number` - 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. + Unix timestamp (in seconds) for when the item was created. - - `CodeInterpreter object { container, type, allowed_callers }` + - `inference_options: object { model, tool_choice }` - A tool that runs Python code to help generate a response to a prompt. + Inference overrides applied to the message. Defaults to null when unset. - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `model: string` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + Model name that generated the response. Defaults to null when using the session default. - - `string` + - `tool_choice: object { id }` - The container ID. + Preferred tool to invoke. Defaults to null when ChatKit should auto-select. - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `id: string` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + Identifier of the requested tool. - - `type: "auto"` + - `object: "chatkit.thread_item"` - Always `auto`. + Type discriminator that is always `chatkit.thread_item`. - - `"auto"` + - `"chatkit.thread_item"` - - `file_ids: optional array of string` + - `thread_id: string` - An optional list of uploaded files to make available to your code. + Identifier of the parent thread. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `type: "chatkit.user_message"` - The memory limit for the code interpreter container. + - `"chatkit.user_message"` - - `"1g"` + - `ChatKitThreadAssistantMessageItem object { id, content, created_at, 3 more }` - - `"4g"` + Assistant-authored message within a thread. - - `"16g"` + - `id: string` - - `"64g"` + Identifier of the thread item. - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `content: array of ChatKitResponseOutputText` - Network access policy for the container. + Ordered assistant response segments. - - `BetaContainerNetworkPolicyDisabled object { type }` + - `annotations: array of object { source, type } or object { source, type }` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + Ordered list of annotations attached to the response text. - - `type: "code_interpreter"` + - `File object { source, type }` - The type of the code interpreter tool. Always `code_interpreter`. + Annotation that references an uploaded file. - - `"code_interpreter"` + - `source: object { filename, type }` - - `allowed_callers: optional array of "direct" or "programmatic"` + File attachment referenced by the annotation. - The tool invocation context(s). + - `filename: string` - - `"direct"` + Filename referenced by the annotation. - - `"programmatic"` + - `type: "file"` - - `ProgrammaticToolCalling object { type }` + Type discriminator that is always `file`. - - `type: "programmatic_tool_calling"` + - `"file"` - The type of the tool. Always `programmatic_tool_calling`. + - `type: "file"` - - `"programmatic_tool_calling"` + Type discriminator that is always `file` for this annotation. - - `ImageGeneration object { type, action, background, 9 more }` + - `"file"` - A tool that generates images using the GPT image models. + - `URL object { source, type }` - - `type: "image_generation"` + Annotation that references a URL. - The type of the image generation tool. Always `image_generation`. + - `source: object { type, url }` - - `"image_generation"` + URL referenced by the annotation. - - `action: optional "generate" or "edit" or "auto"` + - `type: "url"` - Whether to generate a new image or edit an existing image. Default: `auto`. + Type discriminator that is always `url`. - - `"generate"` + - `"url"` - - `"edit"` + - `url: string` - - `"auto"` + URL referenced by the annotation. - - `background: optional "transparent" or "opaque" or "auto"` + - `type: "url"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + Type discriminator that is always `url` for this annotation. - - `"transparent"` + - `"url"` - - `"opaque"` + - `text: string` - - `"auto"` + Assistant generated text. - - `input_fidelity: optional "high" or "low"` + - `type: "output_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`. + Type discriminator that is always `output_text`. - - `"high"` + - `"output_text"` - - `"low"` + - `created_at: number` - - `input_image_mask: optional object { file_id, image_url }` + Unix timestamp (in seconds) for when the item was created. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `object: "chatkit.thread_item"` - - `file_id: optional string` + Type discriminator that is always `chatkit.thread_item`. - File ID for the mask image. + - `"chatkit.thread_item"` - - `image_url: optional string` + - `thread_id: string` - Base64-encoded mask image. + Identifier of the parent thread. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `type: "chatkit.assistant_message"` - The image generation model to use. Default: `gpt-image-1`. + Type discriminator that is always `chatkit.assistant_message`. - - `string` + - `"chatkit.assistant_message"` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `ChatKitWidgetItem object { id, created_at, object, 3 more }` - The image generation model to use. Default: `gpt-image-1`. + Thread item that renders a widget payload. - - `"gpt-image-1"` + - `id: string` - - `"gpt-image-1-mini"` + Identifier of the thread item. - - `"gpt-image-1.5"` + - `created_at: number` - - `moderation: optional "auto" or "low"` + Unix timestamp (in seconds) for when the item was created. - Moderation level for the generated image. Default: `auto`. + - `object: "chatkit.thread_item"` - - `"auto"` + Type discriminator that is always `chatkit.thread_item`. - - `"low"` + - `"chatkit.thread_item"` - - `output_compression: optional number` + - `thread_id: string` - Compression level for the output image. Default: 100. + Identifier of the parent thread. - - `output_format: optional "png" or "webp" or "jpeg"` + - `type: "chatkit.widget"` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + Type discriminator that is always `chatkit.widget`. - - `"png"` + - `"chatkit.widget"` - - `"webp"` + - `widget: string` - - `"jpeg"` + Serialized widget payload rendered in the UI. - - `partial_images: optional number` + - `ChatKitClientToolCall object { id, arguments, call_id, 7 more }` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + Record of a client side tool invocation initiated by the assistant. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `id: string` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + Identifier of the thread item. - - `"low"` + - `arguments: string` - - `"medium"` + JSON-encoded arguments that were sent to the tool. - - `"high"` + - `call_id: string` - - `"auto"` + Identifier for the client tool call. - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `created_at: number` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + Unix timestamp (in seconds) for when the item was created. - - `string` + - `name: string` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + Tool name that was invoked. - 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`. + - `object: "chatkit.thread_item"` - - `"1024x1024"` + Type discriminator that is always `chatkit.thread_item`. - - `"1024x1536"` + - `"chatkit.thread_item"` - - `"1536x1024"` + - `output: string` - - `"auto"` + JSON-encoded output captured from the tool. Defaults to null while execution is in progress. - - `LocalShell object { type }` + - `status: "in_progress" or "completed"` - A tool that allows the model to execute shell commands in a local environment. + Execution status for the tool call. - - `type: "local_shell"` + - `"in_progress"` - The type of the local shell tool. Always `local_shell`. + - `"completed"` - - `"local_shell"` + - `thread_id: string` - - `Shell object { type, allowed_callers, environment }` + Identifier of the parent thread. - A tool that allows the model to execute shell commands. + - `type: "chatkit.client_tool_call"` - - `type: "shell"` + Type discriminator that is always `chatkit.client_tool_call`. - The type of the shell tool. Always `shell`. + - `"chatkit.client_tool_call"` - - `"shell"` + - `ChatKitTask object { id, created_at, heading, 5 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + Task emitted by the workflow to show progress and status updates. - The tool invocation context(s). + - `id: string` - - `"direct"` + Identifier of the thread item. - - `"programmatic"` + - `created_at: number` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + Unix timestamp (in seconds) for when the item was created. - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `heading: string` - - `BetaLocalEnvironment object { type, skills }` + Optional heading for the task. Defaults to null when not provided. - - `BetaContainerReference object { container_id, type }` + - `object: "chatkit.thread_item"` - - `Custom object { name, type, allowed_callers, 3 more }` + Type discriminator that is always `chatkit.thread_item`. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `"chatkit.thread_item"` - - `name: string` + - `summary: string` - The name of the custom tool, used to identify it in tool calls. + Optional summary that describes the task. Defaults to null when omitted. - - `type: "custom"` + - `task_type: "custom" or "thought"` - The type of the custom tool. Always `custom`. + Subtype for the task. - `"custom"` - - `allowed_callers: optional array of "direct" or "programmatic"` - - The tool invocation context(s). + - `"thought"` - - `"direct"` + - `thread_id: string` - - `"programmatic"` + Identifier of the parent thread. - - `defer_loading: optional boolean` + - `type: "chatkit.task"` - Whether this tool should be deferred and discovered via tool search. + Type discriminator that is always `chatkit.task`. - - `description: optional string` + - `"chatkit.task"` - Optional description of the custom tool, used to provide more context. + - `ChatKitTaskGroup object { id, created_at, object, 3 more }` - - `format: optional object { type } or object { definition, syntax, type }` + Collection of workflow tasks grouped together in the thread. - The input format for the custom tool. Default is unconstrained text. + - `id: string` - - `Text object { type }` + Identifier of the thread item. - Unconstrained free-form text. + - `created_at: number` - - `type: "text"` + Unix timestamp (in seconds) for when the item was created. - Unconstrained text format. Always `text`. + - `object: "chatkit.thread_item"` - - `"text"` + Type discriminator that is always `chatkit.thread_item`. - - `Grammar object { definition, syntax, type }` + - `"chatkit.thread_item"` - A grammar defined by the user. + - `tasks: array of object { heading, summary, type }` - - `definition: string` + Tasks included in the group. - The grammar definition. + - `heading: string` - - `syntax: "lark" or "regex"` + Optional heading for the grouped task. Defaults to null when not provided. - The syntax of the grammar definition. One of `lark` or `regex`. + - `summary: string` - - `"lark"` + Optional summary that describes the grouped task. Defaults to null when omitted. - - `"regex"` + - `type: "custom" or "thought"` - - `type: "grammar"` + Subtype for the grouped task. - Grammar format. Always `grammar`. + - `"custom"` - - `"grammar"` + - `"thought"` - - `Namespace object { description, name, tools, type }` + - `thread_id: string` - Groups function/custom tools under a shared namespace. + Identifier of the parent thread. - - `description: string` + - `type: "chatkit.task_group"` - A description of the namespace shown to the model. + Type discriminator that is always `chatkit.task_group`. - - `name: string` + - `"chatkit.task_group"` - The namespace name used in tool calls (for example, `crm`). + - `first_id: string` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + The ID of the first item in the list. - The function/custom tools available inside this namespace. + - `has_more: boolean` - - `Function object { name, type, allowed_callers, 5 more }` + Whether there are more items available. - - `name: string` + - `last_id: string` - - `type: "function"` + The ID of the last item in the list. - - `"function"` + - `object: "list"` - - `allowed_callers: optional array of "direct" or "programmatic"` + The type of object returned, must be `list`. - The tool invocation context(s). + - `"list"` - - `"direct"` +### Example - - `"programmatic"` +```http +curl https://api.openai.com/v1/chatkit/threads/$THREAD_ID/items \ + -H 'OpenAI-Beta: chatkit_beta=v1' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `defer_loading: optional boolean` +#### Response - Whether this function should be deferred and discovered via tool search. +```json +{ + "data": [ + { + "id": "id", + "attachments": [ + { + "id": "id", + "mime_type": "mime_type", + "name": "name", + "preview_url": "https://example.com", + "type": "image" + } + ], + "content": [ + { + "text": "text", + "type": "input_text" + } + ], + "created_at": 0, + "inference_options": { + "model": "model", + "tool_choice": { + "id": "id" + } + }, + "object": "chatkit.thread_item", + "thread_id": "thread_id", + "type": "chatkit.user_message" + } + ], + "first_id": "first_id", + "has_more": true, + "last_id": "last_id", + "object": "list" +} +``` - - `description: optional string` +### Example - - `output_schema: optional map[unknown]` +```http +curl "https://api.openai.com/v1/chatkit/threads/cthr_abc123/items?limit=3" \ + -H "OpenAI-Beta: chatkit_beta=v1" \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. +#### Response - - `parameters: optional unknown` +```json +{ + "data": [ + { + "id": "cthi_user_001", + "object": "chatkit.thread_item", + "type": "user_message", + "content": [ + { + "type": "input_text", + "text": "I need help debugging an onboarding issue." + } + ], + "attachments": [] + }, + { + "id": "cthi_assistant_002", + "object": "chatkit.thread_item", + "type": "assistant_message", + "content": [ + { + "type": "output_text", + "text": "Let's start by confirming the workflow version you deployed." + } + ] + } + ], + "has_more": false, + "object": "list" +} +``` - - `strict: optional boolean` +## Retrieve ChatKit thread - 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. +**get** `/chatkit/threads/{thread_id}` - - `Custom object { name, type, allowed_callers, 3 more }` +Retrieve a ChatKit thread by its identifier. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) +### Path Parameters - - `name: string` +- `thread_id: string` - The name of the custom tool, used to identify it in tool calls. +### Returns - - `type: "custom"` +- `ChatKitThread object { id, created_at, object, 3 more }` - The type of the custom tool. Always `custom`. + Represents a ChatKit thread and its current status. - - `"custom"` + - `id: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + Identifier of the thread. - The tool invocation context(s). + - `created_at: number` - - `"direct"` + Unix timestamp (in seconds) for when the thread was created. - - `"programmatic"` + - `object: "chatkit.thread"` - - `defer_loading: optional boolean` + Type discriminator that is always `chatkit.thread`. - Whether this tool should be deferred and discovered via tool search. + - `"chatkit.thread"` - - `description: optional string` + - `status: object { type } or object { reason, type } or object { reason, type }` - Optional description of the custom tool, used to provide more context. + Current status for the thread. Defaults to `active` for newly created threads. - - `format: optional object { type } or object { definition, syntax, type }` + - `Active object { type }` - The input format for the custom tool. Default is unconstrained text. + Indicates that a thread is active. - - `Text object { type }` + - `type: "active"` - Unconstrained free-form text. + Status discriminator that is always `active`. - - `type: "text"` + - `"active"` - Unconstrained text format. Always `text`. + - `Locked object { reason, type }` - - `"text"` + Indicates that a thread is locked and cannot accept new input. - - `Grammar object { definition, syntax, type }` + - `reason: string` - A grammar defined by the user. + Reason that the thread was locked. Defaults to null when no reason is recorded. - - `definition: string` + - `type: "locked"` - The grammar definition. + Status discriminator that is always `locked`. - - `syntax: "lark" or "regex"` + - `"locked"` - The syntax of the grammar definition. One of `lark` or `regex`. + - `Closed object { reason, type }` - - `"lark"` + Indicates that a thread has been closed. - - `"regex"` + - `reason: string` - - `type: "grammar"` + Reason that the thread was closed. Defaults to null when no reason is recorded. - Grammar format. Always `grammar`. + - `type: "closed"` - - `"grammar"` + Status discriminator that is always `closed`. - - `type: "namespace"` + - `"closed"` - The type of the tool. Always `namespace`. + - `title: string` - - `"namespace"` + Optional human-readable title for the thread. Defaults to null when no title has been generated. - - `ToolSearch object { type, description, execution, parameters }` + - `user: string` - Hosted or BYOT tool search configuration for deferred tools. + Free-form string that identifies your end user who owns the thread. - - `type: "tool_search"` +### Example - The type of the tool. Always `tool_search`. +```http +curl https://api.openai.com/v1/chatkit/threads/$THREAD_ID \ + -H 'OpenAI-Beta: chatkit_beta=v1' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `"tool_search"` +#### Response - - `description: optional string` +```json +{ + "id": "cthr_def456", + "created_at": 1712345600, + "object": "chatkit.thread", + "status": { + "type": "active" + }, + "title": "Demo feedback", + "user": "user_456" +} +``` - Description shown to the model for a client-executed tool search tool. +### Example - - `execution: optional "server" or "client"` +```http +curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ + -H "OpenAI-Beta: chatkit_beta=v1" \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - Whether tool search is executed by the server or by the client. +#### Response - - `"server"` +```json +{ + "id": "cthr_abc123", + "object": "chatkit.thread", + "title": "Customer escalation", + "items": { + "data": [ + { + "id": "cthi_user_001", + "object": "chatkit.thread_item", + "type": "user_message", + "content": [ + { + "type": "input_text", + "text": "I need help debugging an onboarding issue." + } + ], + "attachments": [] + }, + { + "id": "cthi_assistant_002", + "object": "chatkit.thread_item", + "type": "assistant_message", + "content": [ + { + "type": "output_text", + "text": "Let's start by confirming the workflow version you deployed." + } + ] + } + ], + "has_more": false + } +} +``` - - `"client"` +## Domain Types - - `parameters: optional unknown` +### Chat Session - Parameter schema for a client-executed tool search tool. +- `ChatSession object { id, chatkit_configuration, client_secret, 7 more }` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + Represents a ChatKit session and its resolved configuration. - 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). + - `id: string` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + Identifier for the ChatKit session. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `chatkit_configuration: ChatSessionChatKitConfiguration` - - `"web_search_preview"` + Resolved ChatKit feature configuration for the session. - - `"web_search_preview_2025_03_11"` + - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` - - `search_content_types: optional array of "text" or "image"` + Automatic thread titling preferences. - - `"text"` + - `enabled: boolean` - - `"image"` + Whether automatic thread titling is enabled. - - `search_context_size: optional "low" or "medium" or "high"` + - `file_upload: ChatSessionFileUpload` - 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. + Upload settings for the session. - - `"low"` + - `enabled: boolean` - - `"medium"` + Indicates if uploads are enabled for the session. - - `"high"` + - `max_file_size: number` - - `user_location: optional object { type, city, country, 2 more }` + Maximum upload size in megabytes. - The user's location. + - `max_files: number` - - `type: "approximate"` + Maximum number of uploads allowed during the session. - The type of location approximation. Always `approximate`. + - `history: ChatSessionHistory` - - `"approximate"` + History retention configuration. - - `city: optional string` + - `enabled: boolean` - Free text input for the city of the user, e.g. `San Francisco`. + Indicates if chat history is persisted for the session. - - `country: optional string` + - `recent_threads: number` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + Number of prior threads surfaced in history views. Defaults to null when all history is retained. - - `region: optional string` + - `client_secret: string` - Free text input for the region of the user, e.g. `California`. + Ephemeral client secret that authenticates session requests. - - `timezone: optional string` + - `expires_at: number` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + Unix timestamp (in seconds) for when the session expires. - - `ApplyPatch object { type, allowed_callers }` + - `max_requests_per_1_minute: number` - Allows the assistant to create, delete, or update files using unified diffs. + Convenience copy of the per-minute request limit. - - `type: "apply_patch"` + - `object: "chatkit.session"` - The type of the tool. Always `apply_patch`. + Type discriminator that is always `chatkit.session`. - - `"apply_patch"` + - `"chatkit.session"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `rate_limits: ChatSessionRateLimits` - The tool invocation context(s). + Resolved rate limit values. - - `"direct"` + - `max_requests_per_1_minute: number` - - `"programmatic"` + Maximum allowed requests per one-minute window. -- `top_logprobs: optional number` + - `status: ChatSessionStatus` - 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. + Current lifecycle state of the session. -- `top_p: optional number` + - `"active"` - 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. + - `"expired"` - We generally recommend altering this or `temperature` but not both. + - `"cancelled"` -- `truncation: optional "auto" or "disabled"` + - `user: string` - The truncation strategy to use for the model response. + User identifier associated with the session. - - `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. + - `workflow: ChatKitWorkflow` - - `"auto"` + Workflow metadata for the session. - - `"disabled"` + - `id: string` -- `user: optional string` + Identifier of the workflow backing the session. - 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). + - `state_variables: map[string or boolean or number]` -### Returns + State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. -- `BetaResponse object { id, created_at, error, 32 more }` + - `string` - - `id: string` + - `boolean` - Unique identifier for this Response. + - `number` - - `created_at: number` + - `tracing: object { enabled }` - Unix timestamp (in seconds) of when this Response was created. + Tracing settings applied to the workflow. - - `error: BetaResponseError` + - `enabled: boolean` - An error object returned when the model fails to generate a Response. + Indicates whether tracing is enabled. - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 17 more` + - `version: string` - The error code for the response. + Specific workflow version used for the session. Defaults to null when using the latest deployment. - - `"server_error"` +### Chat Session Automatic Thread Titling - - `"rate_limit_exceeded"` +- `ChatSessionAutomaticThreadTitling object { enabled }` - - `"invalid_prompt"` + Automatic thread title preferences for the session. - - `"data_residency_mismatch"` + - `enabled: boolean` - - `"bio_policy"` + Whether automatic thread titling is enabled. - - `"vector_store_timeout"` +### Chat Session ChatKit Configuration - - `"invalid_image"` +- `ChatSessionChatKitConfiguration object { automatic_thread_titling, file_upload, history }` - - `"invalid_image_format"` + ChatKit configuration for the session. - - `"invalid_base64_image"` + - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` - - `"invalid_image_url"` + Automatic thread titling preferences. - - `"image_too_large"` + - `enabled: boolean` - - `"image_too_small"` + Whether automatic thread titling is enabled. - - `"image_parse_error"` + - `file_upload: ChatSessionFileUpload` - - `"image_content_policy_violation"` + Upload settings for the session. - - `"invalid_image_mode"` + - `enabled: boolean` - - `"image_file_too_large"` + Indicates if uploads are enabled for the session. - - `"unsupported_image_media_type"` + - `max_file_size: number` - - `"empty_image_file"` + Maximum upload size in megabytes. - - `"failed_to_download_image"` + - `max_files: number` - - `"image_file_not_found"` + Maximum number of uploads allowed during the session. - - `message: string` + - `history: ChatSessionHistory` - A human-readable description of the error. + History retention configuration. - - `incomplete_details: object { reason }` + - `enabled: boolean` - Details about why the response is incomplete. + Indicates if chat history is persisted for the session. - - `reason: optional "max_output_tokens" or "content_filter"` + - `recent_threads: number` - The reason why the response is incomplete. + Number of prior threads surfaced in history views. Defaults to null when all history is retained. - - `"max_output_tokens"` +### Chat Session ChatKit Configuration Param - - `"content_filter"` +- `ChatSessionChatKitConfigurationParam object { automatic_thread_titling, file_upload, history }` - - `instructions: string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + Optional per-session configuration settings for ChatKit behavior. - A system (or developer) message inserted into the model's context. + - `automatic_thread_titling: optional object { enabled }` - 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. + Configuration for automatic thread titling. When omitted, automatic thread titling is enabled by default. - - `string` + - `enabled: optional boolean` - A text input to the model, equivalent to a text input with the - `developer` role. + Enable automatic thread title generation. Defaults to true. - - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + - `file_upload: optional object { enabled, max_file_size, max_files }` - A list of one or many input items to the model, containing - different content types. + Configuration for upload enablement and limits. When omitted, uploads are disabled by default (max_files 10, max_file_size 512 MB). - - `BetaEasyInputMessage object { content, role, phase, type }` + - `enabled: optional boolean` - 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. + Enable uploads for this session. Defaults to false. - - `content: string or BetaResponseInputMessageContentList` + - `max_file_size: optional number` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + Maximum size in megabytes for each uploaded file. Defaults to 512 MB, which is the maximum allowable size. - - `TextInput = string` + - `max_files: optional number` - A text input to the model. + Maximum number of files that can be uploaded to the session. Defaults to 10. - - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` + - `history: optional object { enabled, recent_threads }` - A list of one or many input items to the model, containing different content - types. + Configuration for chat history retention. When omitted, history is enabled by default with no limit on recent_threads (null). - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `enabled: optional boolean` - A text input to the model. + Enables chat users to access previous ChatKit threads. Defaults to true. - - `text: string` + - `recent_threads: optional number` - The text input to the model. + Number of recent ChatKit threads users have access to. Defaults to unlimited when unset. - - `type: "input_text"` +### Chat Session Expires After Param - The type of the input item. Always `input_text`. +- `ChatSessionExpiresAfterParam object { anchor, seconds }` - - `"input_text"` + Controls when the session expires relative to an anchor timestamp. - - `prompt_cache_breakpoint: optional object { mode }` + - `anchor: "created_at"` - 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. + Base timestamp used to calculate expiration. Currently fixed to `created_at`. - - `mode: "explicit"` + - `"created_at"` - The breakpoint mode. Always `explicit`. + - `seconds: number` - - `"explicit"` + Number of seconds after the anchor when the session expires. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` +### Chat Session File Upload - An image input to the model. Learn about [image inputs](/docs/guides/vision). +- `ChatSessionFileUpload object { enabled, max_file_size, max_files }` - - `detail: "low" or "high" or "auto" or "original"` + Upload permissions and limits applied to the session. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `enabled: boolean` - - `"low"` + Indicates if uploads are enabled for the session. - - `"high"` + - `max_file_size: number` - - `"auto"` + Maximum upload size in megabytes. - - `"original"` + - `max_files: number` - - `type: "input_image"` + Maximum number of uploads allowed during the session. - The type of the input item. Always `input_image`. +### Chat Session History - - `"input_image"` +- `ChatSessionHistory object { enabled, recent_threads }` - - `file_id: optional string` + History retention preferences returned for the session. - The ID of the file to be sent to the model. + - `enabled: boolean` - - `image_url: optional string` + Indicates if chat history is persisted for the session. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `recent_threads: number` - - `prompt_cache_breakpoint: optional object { mode }` + Number of prior threads surfaced in history views. Defaults to null when all history is retained. - 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. +### Chat Session Rate Limits - - `mode: "explicit"` +- `ChatSessionRateLimits object { max_requests_per_1_minute }` - The breakpoint mode. Always `explicit`. + Active per-minute request limit for the session. - - `"explicit"` + - `max_requests_per_1_minute: number` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + Maximum allowed requests per one-minute window. - A file input to the model. +### Chat Session Rate Limits Param - - `type: "input_file"` +- `ChatSessionRateLimitsParam object { max_requests_per_1_minute }` - The type of the input item. Always `input_file`. + Controls request rate limits for the session. - - `"input_file"` + - `max_requests_per_1_minute: optional number` - - `detail: optional "auto" or "low" or "high"` + Maximum number of requests allowed per minute for the session. Defaults to 10. - 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`. +### Chat Session Status - - `"auto"` +- `ChatSessionStatus = "active" or "expired" or "cancelled"` - - `"low"` + - `"active"` - - `"high"` + - `"expired"` - - `file_data: optional string` + - `"cancelled"` - The content of the file to be sent to the model. +### Chat Session Workflow Param - - `file_id: optional string` +- `ChatSessionWorkflowParam object { id, state_variables, tracing, version }` - The ID of the file to be sent to the model. + Workflow reference and overrides applied to the chat session. - - `file_url: optional string` + - `id: string` - The URL of the file to be sent to the model. + Identifier for the workflow invoked by the session. - - `filename: optional string` + - `state_variables: optional map[string or boolean or number]` - The name of the file to be sent to the model. + State variables forwarded to the workflow. Keys may be up to 64 characters, values must be primitive types, and the map defaults to an empty object. - - `prompt_cache_breakpoint: optional object { mode }` + - `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. + - `boolean` - - `mode: "explicit"` + - `number` - The breakpoint mode. Always `explicit`. + - `tracing: optional object { enabled }` - - `"explicit"` + Optional tracing overrides for the workflow invocation. When omitted, tracing is enabled by default. - - `role: "user" or "assistant" or "system" or "developer"` + - `enabled: optional boolean` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + Whether tracing is enabled during the session. Defaults to true. - - `"user"` + - `version: optional string` - - `"assistant"` + Specific workflow version to run. Defaults to the latest deployed version. - - `"system"` +### ChatKit Attachment - - `"developer"` +- `ChatKitAttachment object { id, mime_type, name, 2 more }` - - `phase: optional "commentary" or "final_answer"` + Attachment metadata included on thread items. - 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. + - `id: string` - - `"commentary"` + Identifier for the attachment. - - `"final_answer"` + - `mime_type: string` - - `type: optional "message"` + MIME type of the attachment. - The type of the message input. Always `message`. + - `name: string` - - `"message"` + Original display name for the attachment. - - `Message object { content, role, agent, 2 more }` + - `preview_url: 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. + Preview URL for rendering the attachment inline. - - `content: BetaResponseInputMessageContentList` + - `type: "image" or "file"` - A list of one or many input items to the model, containing different content - types. + Attachment discriminator. - - `role: "user" or "system" or "developer"` + - `"image"` - The role of the message input. One of `user`, `system`, or `developer`. + - `"file"` - - `"user"` +### ChatKit Response Output Text - - `"system"` +- `ChatKitResponseOutputText object { annotations, text, type }` - - `"developer"` + Assistant response text accompanied by optional annotations. - - `agent: optional object { agent_name }` + - `annotations: array of object { source, type } or object { source, type }` - The agent that produced this item. + Ordered list of annotations attached to the response text. - - `agent_name: string` + - `File object { source, type }` - The canonical name of the agent that produced this item. + Annotation that references an uploaded file. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `source: object { filename, type }` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + File attachment referenced by the annotation. - - `"in_progress"` + - `filename: string` - - `"completed"` + Filename referenced by the annotation. - - `"incomplete"` + - `type: "file"` - - `type: optional "message"` + Type discriminator that is always `file`. - The type of the message input. Always set to `message`. + - `"file"` - - `"message"` + - `type: "file"` - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + Type discriminator that is always `file` for this annotation. - An output message from the model. + - `"file"` - - `id: string` + - `URL object { source, type }` - The unique ID of the output message. + Annotation that references a URL. - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `source: object { type, url }` - The content of the output message. + URL referenced by the annotation. - - `BetaResponseOutputText object { annotations, logprobs, text, type }` + - `type: "url"` - A text output from the model. + Type discriminator that is always `url`. - - `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 }` + - `"url"` - The annotations of the text output. + - `url: string` - - `FileCitation object { file_id, filename, index, type }` + URL referenced by the annotation. - A citation to a file. + - `type: "url"` - - `file_id: string` + Type discriminator that is always `url` for this annotation. - The ID of the file. + - `"url"` - - `filename: string` + - `text: string` - The filename of the file cited. + Assistant generated text. - - `index: number` + - `type: "output_text"` - The index of the file in the list of files. + Type discriminator that is always `output_text`. - - `type: "file_citation"` + - `"output_text"` - The type of the file citation. Always `file_citation`. +### ChatKit Thread - - `"file_citation"` +- `ChatKitThread object { id, created_at, object, 3 more }` - - `URLCitation object { end_index, start_index, title, 2 more }` + Represents a ChatKit thread and its current status. - A citation for a web resource used to generate a model response. + - `id: string` - - `end_index: number` + Identifier of the thread. - The index of the last character of the URL citation in the message. + - `created_at: number` - - `start_index: number` + Unix timestamp (in seconds) for when the thread was created. - The index of the first character of the URL citation in the message. + - `object: "chatkit.thread"` - - `title: string` + Type discriminator that is always `chatkit.thread`. - The title of the web resource. + - `"chatkit.thread"` - - `type: "url_citation"` + - `status: object { type } or object { reason, type } or object { reason, type }` - The type of the URL citation. Always `url_citation`. + Current status for the thread. Defaults to `active` for newly created threads. - - `"url_citation"` + - `Active object { type }` - - `url: string` + Indicates that a thread is active. - The URL of the web resource. + - `type: "active"` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + Status discriminator that is always `active`. - A citation for a container file used to generate a model response. + - `"active"` - - `container_id: string` + - `Locked object { reason, type }` - The ID of the container file. + Indicates that a thread is locked and cannot accept new input. - - `end_index: number` + - `reason: string` - The index of the last character of the container file citation in the message. + Reason that the thread was locked. Defaults to null when no reason is recorded. - - `file_id: string` + - `type: "locked"` - The ID of the file. + Status discriminator that is always `locked`. - - `filename: string` + - `"locked"` - The filename of the container file cited. + - `Closed object { reason, type }` - - `start_index: number` + Indicates that a thread has been closed. - The index of the first character of the container file citation in the message. + - `reason: string` - - `type: "container_file_citation"` + Reason that the thread was closed. Defaults to null when no reason is recorded. - The type of the container file citation. Always `container_file_citation`. + - `type: "closed"` - - `"container_file_citation"` + Status discriminator that is always `closed`. - - `FilePath object { file_id, index, type }` + - `"closed"` - A path to a file. + - `title: string` - - `file_id: string` + Optional human-readable title for the thread. Defaults to null when no title has been generated. - The ID of the file. + - `user: string` - - `index: number` + Free-form string that identifies your end user who owns the thread. - The index of the file in the list of files. +### ChatKit Thread Assistant Message Item - - `type: "file_path"` +- `ChatKitThreadAssistantMessageItem object { id, content, created_at, 3 more }` - The type of the file path. Always `file_path`. + Assistant-authored message within a thread. - - `"file_path"` + - `id: string` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + Identifier of the thread item. - - `token: string` + - `content: array of ChatKitResponseOutputText` - - `bytes: array of number` + Ordered assistant response segments. - - `logprob: number` + - `annotations: array of object { source, type } or object { source, type }` - - `top_logprobs: array of object { token, bytes, logprob }` + Ordered list of annotations attached to the response text. - - `token: string` + - `File object { source, type }` - - `bytes: array of number` + Annotation that references an uploaded file. - - `logprob: number` + - `source: object { filename, type }` - - `text: string` + File attachment referenced by the annotation. - The text output from the model. + - `filename: string` - - `type: "output_text"` + Filename referenced by the annotation. - The type of the output text. Always `output_text`. + - `type: "file"` - - `"output_text"` + Type discriminator that is always `file`. - - `BetaResponseOutputRefusal object { refusal, type }` + - `"file"` - A refusal from the model. + - `type: "file"` - - `refusal: string` + Type discriminator that is always `file` for this annotation. - The refusal explanation from the model. + - `"file"` - - `type: "refusal"` + - `URL object { source, type }` - The type of the refusal. Always `refusal`. + Annotation that references a URL. - - `"refusal"` + - `source: object { type, url }` - - `role: "assistant"` + URL referenced by the annotation. - The role of the output message. Always `assistant`. + - `type: "url"` - - `"assistant"` + Type discriminator that is always `url`. - - `status: "in_progress" or "completed" or "incomplete"` + - `"url"` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `url: string` - - `"in_progress"` + URL referenced by the annotation. - - `"completed"` + - `type: "url"` - - `"incomplete"` + Type discriminator that is always `url` for this annotation. - - `type: "message"` + - `"url"` - The type of the output message. Always `message`. + - `text: string` - - `"message"` + Assistant generated text. - - `agent: optional object { agent_name }` + - `type: "output_text"` - The agent that produced this item. + Type discriminator that is always `output_text`. - - `agent_name: string` + - `"output_text"` - The canonical name of the agent that produced this item. + - `created_at: number` - - `phase: optional "commentary" or "final_answer"` + Unix timestamp (in seconds) for when the item was created. - 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. + - `object: "chatkit.thread_item"` - - `"commentary"` + Type discriminator that is always `chatkit.thread_item`. - - `"final_answer"` + - `"chatkit.thread_item"` - - `FileSearchCall object { id, queries, status, 3 more }` + - `thread_id: string` - The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + Identifier of the parent thread. - - `id: string` + - `type: "chatkit.assistant_message"` - The unique ID of the file search tool call. + Type discriminator that is always `chatkit.assistant_message`. - - `queries: array of string` + - `"chatkit.assistant_message"` - The queries used to search for files. +### ChatKit Thread Item List - - `status: "in_progress" or "searching" or "completed" or 2 more` +- `ChatKitThreadItemList object { data, first_id, has_more, 2 more }` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + A paginated list of thread items rendered for the ChatKit API. - - `"in_progress"` + - `data: array of ChatKitThreadUserMessageItem or ChatKitThreadAssistantMessageItem or ChatKitWidgetItem or 3 more` - - `"searching"` + A list of items - - `"completed"` + - `ChatKitThreadUserMessageItem object { id, attachments, content, 5 more }` - - `"incomplete"` + User-authored messages within a thread. - - `"failed"` + - `id: string` - - `type: "file_search_call"` + Identifier of the thread item. - The type of the file search tool call. Always `file_search_call`. + - `attachments: array of ChatKitAttachment` - - `"file_search_call"` + Attachments associated with the user message. Defaults to an empty list. - - `agent: optional object { agent_name }` + - `id: string` - The agent that produced this item. + Identifier for the attachment. - - `agent_name: string` + - `mime_type: string` - The canonical name of the agent that produced this item. + MIME type of the attachment. - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `name: string` - The results of the file search tool call. + Original display name for the attachment. - - `attributes: optional map[string or number or boolean]` + - `preview_url: string` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + Preview URL for rendering the attachment inline. - - `string` + - `type: "image" or "file"` - - `number` + Attachment discriminator. - - `boolean` + - `"image"` - - `file_id: optional string` + - `"file"` - The unique ID of the file. + - `content: array of object { text, type } or object { text, type }` - - `filename: optional string` + Ordered content elements supplied by the user. - The name of the file. + - `InputText object { text, type }` - - `score: optional number` + Text block that a user contributed to the thread. - The relevance score of the file - a value between 0 and 1. + - `text: string` - - `text: optional string` + Plain-text content supplied by the user. - The text that was retrieved from the file. + - `type: "input_text"` - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + Type discriminator that is always `input_text`. - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + - `"input_text"` - - `id: string` + - `QuotedText object { text, type }` - The unique ID of the computer call. + Quoted snippet that the user referenced in their message. - - `call_id: string` + - `text: string` - An identifier used when responding to the tool call with output. + Quoted text content. - - `pending_safety_checks: array of object { id, code, message }` + - `type: "quoted_text"` - The pending safety checks for the computer call. + Type discriminator that is always `quoted_text`. - - `id: string` + - `"quoted_text"` - The ID of the pending safety check. + - `created_at: number` - - `code: optional string` + Unix timestamp (in seconds) for when the item was created. - The type of the pending safety check. + - `inference_options: object { model, tool_choice }` - - `message: optional string` + Inference overrides applied to the message. Defaults to null when unset. - Details about the pending safety check. + - `model: string` - - `status: "in_progress" or "completed" or "incomplete"` + Model name that generated the response. Defaults to null when using the session default. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `tool_choice: object { id }` - - `"in_progress"` + Preferred tool to invoke. Defaults to null when ChatKit should auto-select. - - `"completed"` + - `id: string` - - `"incomplete"` + Identifier of the requested tool. - - `type: "computer_call"` + - `object: "chatkit.thread_item"` - The type of the computer call. Always `computer_call`. + Type discriminator that is always `chatkit.thread_item`. - - `"computer_call"` + - `"chatkit.thread_item"` - - `action: optional BetaComputerAction` + - `thread_id: string` - A click action. + Identifier of the parent thread. - - `Click object { button, type, x, 2 more }` + - `type: "chatkit.user_message"` - A click action. + - `"chatkit.user_message"` - - `button: "left" or "right" or "wheel" or 2 more` + - `ChatKitThreadAssistantMessageItem object { id, content, created_at, 3 more }` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + Assistant-authored message within a thread. - - `"left"` + - `id: string` - - `"right"` + Identifier of the thread item. - - `"wheel"` + - `content: array of ChatKitResponseOutputText` - - `"back"` + Ordered assistant response segments. - - `"forward"` + - `annotations: array of object { source, type } or object { source, type }` - - `type: "click"` + Ordered list of annotations attached to the response text. - Specifies the event type. For a click action, this property is always `click`. + - `File object { source, type }` - - `"click"` + Annotation that references an uploaded file. - - `x: number` + - `source: object { filename, type }` - The x-coordinate where the click occurred. + File attachment referenced by the annotation. - - `y: number` + - `filename: string` - The y-coordinate where the click occurred. + Filename referenced by the annotation. - - `keys: optional array of string` + - `type: "file"` - The keys being held while clicking. + Type discriminator that is always `file`. - - `DoubleClick object { keys, type, x, y }` + - `"file"` - A double click action. + - `type: "file"` - - `keys: array of string` + Type discriminator that is always `file` for this annotation. - The keys being held while double-clicking. + - `"file"` - - `type: "double_click"` + - `URL object { source, type }` - Specifies the event type. For a double click action, this property is always set to `double_click`. + Annotation that references a URL. - - `"double_click"` + - `source: object { type, url }` - - `x: number` + URL referenced by the annotation. - The x-coordinate where the double click occurred. + - `type: "url"` - - `y: number` + Type discriminator that is always `url`. - The y-coordinate where the double click occurred. + - `"url"` - - `Drag object { path, type, keys }` + - `url: string` - A drag action. + URL referenced by the annotation. - - `path: array of object { x, y }` + - `type: "url"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + Type discriminator that is always `url` for this annotation. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `"url"` - - `x: number` + - `text: string` - The x-coordinate. + Assistant generated text. - - `y: number` + - `type: "output_text"` - The y-coordinate. + Type discriminator that is always `output_text`. - - `type: "drag"` + - `"output_text"` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `created_at: number` - - `"drag"` + Unix timestamp (in seconds) for when the item was created. - - `keys: optional array of string` + - `object: "chatkit.thread_item"` - The keys being held while dragging the mouse. + Type discriminator that is always `chatkit.thread_item`. - - `Keypress object { keys, type }` + - `"chatkit.thread_item"` - A collection of keypresses the model would like to perform. + - `thread_id: string` - - `keys: array of string` + Identifier of the parent thread. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `type: "chatkit.assistant_message"` - - `type: "keypress"` + Type discriminator that is always `chatkit.assistant_message`. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `"chatkit.assistant_message"` - - `"keypress"` + - `ChatKitWidgetItem object { id, created_at, object, 3 more }` - - `Move object { type, x, y, keys }` + Thread item that renders a widget payload. - A mouse move action. + - `id: string` - - `type: "move"` + Identifier of the thread item. - Specifies the event type. For a move action, this property is always set to `move`. + - `created_at: number` - - `"move"` + Unix timestamp (in seconds) for when the item was created. - - `x: number` + - `object: "chatkit.thread_item"` - The x-coordinate to move to. + Type discriminator that is always `chatkit.thread_item`. - - `y: number` + - `"chatkit.thread_item"` - The y-coordinate to move to. + - `thread_id: string` - - `keys: optional array of string` + Identifier of the parent thread. - The keys being held while moving the mouse. + - `type: "chatkit.widget"` - - `Screenshot object { type }` + Type discriminator that is always `chatkit.widget`. - A screenshot action. + - `"chatkit.widget"` - - `type: "screenshot"` + - `widget: string` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + Serialized widget payload rendered in the UI. - - `"screenshot"` + - `ChatKitClientToolCall object { id, arguments, call_id, 7 more }` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + Record of a client side tool invocation initiated by the assistant. - A scroll action. + - `id: string` - - `scroll_x: number` + Identifier of the thread item. - The horizontal scroll distance. + - `arguments: string` - - `scroll_y: number` + JSON-encoded arguments that were sent to the tool. - The vertical scroll distance. + - `call_id: string` - - `type: "scroll"` + Identifier for the client tool call. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `created_at: number` - - `"scroll"` + Unix timestamp (in seconds) for when the item was created. - - `x: number` + - `name: string` - The x-coordinate where the scroll occurred. + Tool name that was invoked. - - `y: number` + - `object: "chatkit.thread_item"` - The y-coordinate where the scroll occurred. + Type discriminator that is always `chatkit.thread_item`. - - `keys: optional array of string` + - `"chatkit.thread_item"` - The keys being held while scrolling. + - `output: string` - - `Type object { text, type }` + JSON-encoded output captured from the tool. Defaults to null while execution is in progress. - An action to type in text. + - `status: "in_progress" or "completed"` - - `text: string` + Execution status for the tool call. - The text to type. + - `"in_progress"` - - `type: "type"` + - `"completed"` - Specifies the event type. For a type action, this property is always set to `type`. + - `thread_id: string` - - `"type"` + Identifier of the parent thread. - - `Wait object { type }` + - `type: "chatkit.client_tool_call"` - A wait action. + Type discriminator that is always `chatkit.client_tool_call`. - - `type: "wait"` + - `"chatkit.client_tool_call"` - Specifies the event type. For a wait action, this property is always set to `wait`. + - `ChatKitTask object { id, created_at, heading, 5 more }` - - `"wait"` + Task emitted by the workflow to show progress and status updates. - - `actions: optional BetaComputerActionList` + - `id: string` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + Identifier of the thread item. - - `Click object { button, type, x, 2 more }` + - `created_at: number` - A click action. + Unix timestamp (in seconds) for when the item was created. - - `DoubleClick object { keys, type, x, y }` + - `heading: string` - A double click action. + Optional heading for the task. Defaults to null when not provided. - - `Drag object { path, type, keys }` + - `object: "chatkit.thread_item"` - A drag action. + Type discriminator that is always `chatkit.thread_item`. - - `Keypress object { keys, type }` + - `"chatkit.thread_item"` - A collection of keypresses the model would like to perform. + - `summary: string` - - `Move object { type, x, y, keys }` + Optional summary that describes the task. Defaults to null when omitted. - A mouse move action. + - `task_type: "custom" or "thought"` - - `Screenshot object { type }` + Subtype for the task. - A screenshot action. + - `"custom"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `"thought"` - A scroll action. + - `thread_id: string` - - `Type object { text, type }` + Identifier of the parent thread. - An action to type in text. + - `type: "chatkit.task"` - - `Wait object { type }` + Type discriminator that is always `chatkit.task`. - A wait action. + - `"chatkit.task"` - - `agent: optional object { agent_name }` + - `ChatKitTaskGroup object { id, created_at, object, 3 more }` - The agent that produced this item. + Collection of workflow tasks grouped together in the thread. - - `agent_name: string` + - `id: string` - The canonical name of the agent that produced this item. + Identifier of the thread item. - - `ComputerCallOutput object { call_id, output, type, 4 more }` + - `created_at: number` - The output of a computer tool call. + Unix timestamp (in seconds) for when the item was created. - - `call_id: string` + - `object: "chatkit.thread_item"` - The ID of the computer tool call that produced the output. + Type discriminator that is always `chatkit.thread_item`. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `"chatkit.thread_item"` - A computer screenshot image used with the computer use tool. + - `tasks: array of object { heading, summary, type }` - - `type: "computer_screenshot"` + Tasks included in the group. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `heading: string` - - `"computer_screenshot"` + Optional heading for the grouped task. Defaults to null when not provided. - - `file_id: optional string` + - `summary: string` - The identifier of an uploaded file that contains the screenshot. + Optional summary that describes the grouped task. Defaults to null when omitted. - - `image_url: optional string` + - `type: "custom" or "thought"` - The URL of the screenshot image. + Subtype for the grouped task. - - `type: "computer_call_output"` + - `"custom"` - The type of the computer tool call output. Always `computer_call_output`. + - `"thought"` - - `"computer_call_output"` + - `thread_id: string` - - `id: optional string` + Identifier of the parent thread. - The ID of the computer tool call output. + - `type: "chatkit.task_group"` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + Type discriminator that is always `chatkit.task_group`. - The safety checks reported by the API that have been acknowledged by the developer. + - `"chatkit.task_group"` + + - `first_id: string` + + The ID of the first item in the list. + + - `has_more: boolean` + + Whether there are more items available. + + - `last_id: string` + + The ID of the last item in the list. + + - `object: "list"` + + The type of object returned, must be `list`. + + - `"list"` + +### ChatKit Thread User Message Item + +- `ChatKitThreadUserMessageItem object { id, attachments, content, 5 more }` + + User-authored messages within a thread. - `id: string` - The ID of the pending safety check. + Identifier of the thread item. - - `code: optional string` + - `attachments: array of ChatKitAttachment` - The type of the pending safety check. + Attachments associated with the user message. Defaults to an empty list. - - `message: optional string` + - `id: string` - Details about the pending safety check. + Identifier for the attachment. - - `agent: optional object { agent_name }` + - `mime_type: string` - The agent that produced this item. + MIME type of the attachment. - - `agent_name: string` + - `name: string` - The canonical name of the agent that produced this item. + Original display name for the attachment. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `preview_url: string` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + Preview URL for rendering the attachment inline. - - `"in_progress"` + - `type: "image" or "file"` - - `"completed"` + Attachment discriminator. - - `"incomplete"` + - `"image"` - - `WebSearchCall object { id, action, status, 2 more }` + - `"file"` - The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + - `content: array of object { text, type } or object { text, type }` - - `id: string` + Ordered content elements supplied by the user. - The unique ID of the web search tool call. + - `InputText object { text, type }` - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + Text block that a user contributed to the thread. - 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). + - `text: string` - - `Search object { type, queries, query, sources }` + Plain-text content supplied by the user. - Action type "search" - Performs a web search query. + - `type: "input_text"` - - `type: "search"` + Type discriminator that is always `input_text`. - The action type. + - `"input_text"` - - `"search"` + - `QuotedText object { text, type }` - - `queries: optional array of string` + Quoted snippet that the user referenced in their message. - The search queries. + - `text: string` - - `query: optional string` + Quoted text content. - The search query. + - `type: "quoted_text"` - - `sources: optional array of object { type, url }` + Type discriminator that is always `quoted_text`. - The sources used in the search. + - `"quoted_text"` - - `type: "url"` + - `created_at: number` - The type of source. Always `url`. + Unix timestamp (in seconds) for when the item was created. - - `"url"` + - `inference_options: object { model, tool_choice }` - - `url: string` + Inference overrides applied to the message. Defaults to null when unset. - The URL of the source. + - `model: string` - - `OpenPage object { type, url }` + Model name that generated the response. Defaults to null when using the session default. - Action type "open_page" - Opens a specific URL from search results. + - `tool_choice: object { id }` - - `type: "open_page"` + Preferred tool to invoke. Defaults to null when ChatKit should auto-select. - The action type. + - `id: string` - - `"open_page"` + Identifier of the requested tool. - - `url: optional string` + - `object: "chatkit.thread_item"` - The URL opened by the model. + Type discriminator that is always `chatkit.thread_item`. - - `FindInPage object { pattern, type, url }` + - `"chatkit.thread_item"` - Action type "find_in_page": Searches for a pattern within a loaded page. + - `thread_id: string` - - `pattern: string` + Identifier of the parent thread. - The pattern or text to search for within the page. + - `type: "chatkit.user_message"` - - `type: "find_in_page"` + - `"chatkit.user_message"` - The action type. +### ChatKit Widget Item - - `"find_in_page"` +- `ChatKitWidgetItem object { id, created_at, object, 3 more }` - - `url: string` + Thread item that renders a widget payload. - The URL of the page searched for the pattern. + - `id: string` - - `status: "in_progress" or "searching" or "completed" or "failed"` + Identifier of the thread item. - The status of the web search tool call. + - `created_at: number` - - `"in_progress"` + Unix timestamp (in seconds) for when the item was created. - - `"searching"` + - `object: "chatkit.thread_item"` - - `"completed"` + Type discriminator that is always `chatkit.thread_item`. - - `"failed"` + - `"chatkit.thread_item"` - - `type: "web_search_call"` + - `thread_id: string` - The type of the web search tool call. Always `web_search_call`. + Identifier of the parent thread. - - `"web_search_call"` + - `type: "chatkit.widget"` - - `agent: optional object { agent_name }` + Type discriminator that is always `chatkit.widget`. - The agent that produced this item. + - `"chatkit.widget"` - - `agent_name: string` + - `widget: string` - The canonical name of the agent that produced this item. + Serialized widget payload rendered in the UI. - - `FunctionCall object { arguments, call_id, name, 6 more }` +### Thread Delete Response - A tool call to run a function. See the - [function calling guide](/docs/guides/function-calling) for more information. +- `ThreadDeleteResponse object { id, deleted, object }` - - `arguments: string` + Confirmation payload returned after deleting a thread. - A JSON string of the arguments to pass to the function. + - `id: string` - - `call_id: string` + Identifier of the deleted thread. - The unique ID of the function tool call generated by the model. + - `deleted: boolean` - - `name: string` + Indicates that the thread has been deleted. - The name of the function to run. + - `object: "chatkit.thread.deleted"` - - `type: "function_call"` + Type discriminator that is always `chatkit.thread.deleted`. - The type of the function tool call. Always `function_call`. + - `"chatkit.thread.deleted"` - - `"function_call"` +# Responses - - `id: optional string` +## Cancel a response - The unique ID of the function tool call. +**post** `/responses/{response_id}/cancel?beta=true` - - `agent: optional object { agent_name }` +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). - The agent that produced this item. +### Header Parameters - - `agent_name: string` +- `"openai-beta": optional array of "responses_multi_agent=v1"` - The canonical name of the agent that produced this item. + - `"responses_multi_agent=v1"` - - `caller: optional object { type } or object { caller_id, type }` +### Path Parameters - The execution context that produced this tool call. +- `response_id: string` - - `Direct object { type }` +### Returns - - `type: "direct"` +- `BetaResponse object { id, created_at, error, 32 more }` - - `"direct"` + - `id: string` - - `Program object { caller_id, type }` + Unique identifier for this Response. - - `caller_id: string` + - `created_at: number` - The call ID of the program item that produced this tool call. + Unix timestamp (in seconds) of when this Response was created. - - `type: "program"` + - `error: BetaResponseError` - - `"program"` + An error object returned when the model fails to generate a Response. - - `namespace: optional string` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 17 more` - The namespace of the function to run. + The error code for the response. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"server_error"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"rate_limit_exceeded"` - - `"in_progress"` + - `"invalid_prompt"` - - `"completed"` + - `"data_residency_mismatch"` - - `"incomplete"` + - `"bio_policy"` - - `FunctionCallOutput object { call_id, output, type, 4 more }` + - `"vector_store_timeout"` - The output of a function tool call. + - `"invalid_image"` - - `call_id: string` + - `"invalid_image_format"` - The unique ID of the function tool call generated by the model. + - `"invalid_base64_image"` - - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` + - `"invalid_image_url"` - Text, image, or file output of the function tool call. + - `"image_too_large"` + + - `"image_too_small"` + + - `"image_parse_error"` + + - `"image_content_policy_violation"` + + - `"invalid_image_mode"` + + - `"image_file_too_large"` + + - `"unsupported_image_media_type"` + + - `"empty_image_file"` + + - `"failed_to_download_image"` + + - `"image_file_not_found"` + + - `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 BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 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 JSON string of the output of the function tool call. + A text input to the model, equivalent to a text input with the + `developer` role. - - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` + - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - An array of content outputs (text, image, file) for the function tool call. + A list of one or many input items to the model, containing + different content types. - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + - `BetaEasyInputMessage object { content, role, phase, type }` + + A message input to the model with a role indicating instruction following + hierarchy. Instructions given with the `developer` or `system` role take + precedence over instructions given with the `user` role. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. + + - `content: string or BetaResponseInputMessageContentList` + + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. + + - `TextInput = string` + + A text input to the model. + + - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` + + A list of one or many input items to the model, containing different content + types. + + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. @@ -7850,17 +8467,11 @@ as input for the model's response. - `"explicit"` - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](/docs/guides/vision) - - - `type: "input_image"` - - The type of the input item. Always `input_image`. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `"input_image"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `detail: optional "low" or "high" or "auto" or "original"` + - `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`. @@ -7872,6 +8483,12 @@ as input for the model's response. - `"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. @@ -7890,7 +8507,7 @@ as input for the model's response. - `"explicit"` - - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. @@ -7912,7 +8529,7 @@ as input for the model's response. - `file_data: optional string` - The base64-encoded data of the file to be sent to the model. + The content of the file to be sent to the model. - `file_id: optional string` @@ -7936,51 +8553,68 @@ as input for the model's response. - `"explicit"` - - `type: "function_call_output"` + - `role: "user" or "assistant" or "system" or "developer"` - The type of the function tool call output. Always `function_call_output`. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `"function_call_output"` + - `"user"` - - `id: optional string` + - `"assistant"` - The unique ID of the function tool call output. Populated when this item is returned via API. + - `"system"` - - `agent: optional object { agent_name }` + - `"developer"` - The agent that produced this item. + - `phase: optional "commentary" or "final_answer"` - - `agent_name: 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 canonical name of the agent that produced this item. + - `"commentary"` - - `caller: optional object { type } or object { caller_id, type }` + - `"final_answer"` - The execution context that produced this tool call. + - `type: optional "message"` - - `Direct object { type }` + The type of the message input. Always `message`. - - `type: "direct"` + - `"message"` - The caller type. Always `direct`. + - `Message object { content, role, agent, 2 more }` - - `"direct"` + 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 object { caller_id, type }` + - `content: BetaResponseInputMessageContentList` - - `caller_id: string` + A list of one or many input items to the model, containing different content + types. - The call ID of the program item that produced this tool call. + - `role: "user" or "system" or "developer"` - - `type: "program"` + The role of the message input. One of `user`, `system`, or `developer`. - The caller type. Always `program`. + - `"user"` - - `"program"` + - `"system"` + + - `"developer"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. - `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 item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -7988,227 +8622,242 @@ as input for the model's response. - `"incomplete"` - - `AgentMessage object { author, content, recipient, 3 more }` + - `type: optional "message"` - A message routed between agents. + The type of the message input. Always set to `message`. - - `author: string` + - `"message"` - The sending agent identity. + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` + An output message from the model. - Plaintext, image, or encrypted content sent between agents. + - `id: string` - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + The unique ID of the output message. - A text input to the model. + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + The content of the output message. - An image input to the model. Learn about [image inputs](/docs/guides/vision) + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - - `EncryptedContent object { encrypted_content, type }` + A text output from the model. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `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 }` - - `encrypted_content: string` + The annotations of the text output. - Opaque encrypted content. + - `FileCitation object { file_id, filename, index, type }` - - `type: "encrypted_content"` + A citation to a file. - The type of the input item. Always `encrypted_content`. + - `file_id: string` - - `"encrypted_content"` + The ID of the file. - - `recipient: string` + - `filename: string` - The destination agent identity. + The filename of the file cited. - - `type: "agent_message"` + - `index: number` - The item type. Always `agent_message`. + The index of the file in the list of files. - - `"agent_message"` + - `type: "file_citation"` - - `id: optional string` + The type of the file citation. Always `file_citation`. - The unique ID of this agent message item. + - `"file_citation"` - - `agent: optional object { agent_name }` + - `URLCitation object { end_index, start_index, title, 2 more }` - The agent that produced this item. + A citation for a web resource used to generate a model response. - - `agent_name: string` + - `end_index: number` - The canonical name of the agent that produced this item. + The index of the last character of the URL citation in the message. - - `MultiAgentCall object { action, arguments, call_id, 3 more }` + - `start_index: number` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + The index of the first character of the URL citation in the message. - The multi-agent action that was executed. + - `title: string` - - `"spawn_agent"` + The title of the web resource. - - `"interrupt_agent"` + - `type: "url_citation"` - - `"list_agents"` + The type of the URL citation. Always `url_citation`. - - `"send_message"` + - `"url_citation"` - - `"followup_task"` + - `url: string` - - `"wait_agent"` + The URL of the web resource. - - `arguments: string` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - The action arguments as a JSON string. + A citation for a container file used to generate a model response. - - `call_id: string` + - `container_id: string` - The unique ID linking this call to its output. + The ID of the container file. - - `type: "multi_agent_call"` + - `end_index: number` - The item type. Always `multi_agent_call`. + The index of the last character of the container file citation in the message. - - `"multi_agent_call"` + - `file_id: string` - - `id: optional string` + The ID of the file. - The unique ID of this multi-agent call. + - `filename: string` - - `agent: optional object { agent_name }` + The filename of the container file cited. - The agent that produced this item. + - `start_index: number` - - `agent_name: string` + The index of the first character of the container file citation in the message. - The canonical name of the agent that produced this item. + - `type: "container_file_citation"` - - `MultiAgentCallOutput object { action, call_id, output, 3 more }` + The type of the container file citation. Always `container_file_citation`. - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `"container_file_citation"` - The multi-agent action that produced this result. + - `FilePath object { file_id, index, type }` - - `"spawn_agent"` + A path to a file. - - `"interrupt_agent"` + - `file_id: string` - - `"list_agents"` + The ID of the file. - - `"send_message"` + - `index: number` - - `"followup_task"` + The index of the file in the list of files. - - `"wait_agent"` + - `type: "file_path"` - - `call_id: string` + The type of the file path. Always `file_path`. - The unique ID of the multi-agent call. + - `"file_path"` - - `output: array of object { text, type, annotations }` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - Text output returned by the multi-agent action. + - `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 content. + The text output from the model. - `type: "output_text"` - The content type. Always `output_text`. + The type of the output text. Always `output_text`. - `"output_text"` - - `annotations: optional 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 }` - - Citations associated with the text content. + - `BetaResponseOutputRefusal object { refusal, type }` - - `FileCitation object { file_id, filename, index, type }` + A refusal from the model. - - `file_id: string` + - `refusal: string` - The ID of the file. + The refusal explanation from the model. - - `filename: string` + - `type: "refusal"` - The filename of the file cited. + The type of the refusal. Always `refusal`. - - `index: number` + - `"refusal"` - The index of the file in the list of files. + - `role: "assistant"` - - `type: "file_citation"` + The role of the output message. Always `assistant`. - The citation type. Always `file_citation`. + - `"assistant"` - - `"file_citation"` + - `status: "in_progress" or "completed" or "incomplete"` - - `URLCitation object { end_index, start_index, title, 2 more }` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `end_index: number` + - `"in_progress"` - The index of the last character of the citation in the message. + - `"completed"` - - `start_index: number` + - `"incomplete"` - The index of the first character of the citation in the message. + - `type: "message"` - - `title: string` + The type of the output message. Always `message`. - The title of the cited resource. + - `"message"` - - `type: "url_citation"` + - `agent: optional object { agent_name }` - The citation type. Always `url_citation`. + The agent that produced this item. - - `"url_citation"` + - `agent_name: string` - - `url: string` + The canonical name of the agent that produced this item. - The URL of the cited resource. + - `phase: optional "commentary" or "final_answer"` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + 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. - - `container_id: string` + - `"commentary"` - The ID of the container. + - `"final_answer"` - - `end_index: number` + - `FileSearchCall object { id, queries, status, 3 more }` - The index of the last character of the citation in the message. + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - - `file_id: string` + - `id: string` - The ID of the container file. + The unique ID of the file search tool call. - - `filename: string` + - `queries: array of string` - The filename of the container file cited. + The queries used to search for files. - - `start_index: number` + - `status: "in_progress" or "searching" or "completed" or 2 more` - The index of the first character of the citation in the message. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `type: "container_file_citation"` + - `"in_progress"` - The citation type. Always `container_file_citation`. + - `"searching"` - - `"container_file_citation"` + - `"completed"` - - `type: "multi_agent_call_output"` + - `"incomplete"` - The item type. Always `multi_agent_call_output`. + - `"failed"` - - `"multi_agent_call_output"` + - `type: "file_search_call"` - - `id: optional string` + The type of the file search tool call. Always `file_search_call`. - The unique ID of this multi-agent call output. + - `"file_search_call"` - `agent: optional object { agent_name }` @@ -8218,162 +8867,1143 @@ as input for the model's response. The canonical name of the agent that produced this item. - - `ToolSearchCall object { arguments, type, id, 4 more }` - - - `arguments: unknown` - - The arguments supplied to the tool search call. + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `type: "tool_search_call"` + The results of the file search tool call. - The item type. Always `tool_search_call`. + - `attributes: optional map[string or number or boolean]` - - `"tool_search_call"` + 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. - - `id: optional string` + - `string` - The unique ID of this tool search call. + - `number` - - `agent: optional object { agent_name }` + - `boolean` - The agent that produced this item. + - `file_id: optional string` - - `agent_name: string` + The unique ID of the file. - The canonical name of the agent that produced this item. + - `filename: optional string` - - `call_id: optional string` + The name of the file. - The unique ID of the tool search call generated by the model. + - `score: optional number` - - `execution: optional "server" or "client"` + The relevance score of the file - a value between 0 and 1. - Whether tool search was executed by the server or by the client. + - `text: optional string` - - `"server"` + The text that was retrieved from the file. - - `"client"` + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - - `status: optional "in_progress" or "completed" or "incomplete"` + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - The status of the tool search call. + - `id: string` - - `"in_progress"` + The unique ID of the computer call. - - `"completed"` + - `call_id: string` - - `"incomplete"` + An identifier used when responding to the tool call with output. - - `ToolSearchOutput object { tools, type, id, 4 more }` + - `pending_safety_checks: array of object { id, code, 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` + The pending safety checks for the computer call. - The loaded tool definitions returned by the tool search output. + - `id: string` - - `Function object { name, parameters, strict, 5 more }` + The ID of the pending safety check. - 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). + - `code: optional string` - - `name: string` + The type of the pending safety check. - The name of the function to call. + - `message: optional string` - - `parameters: map[unknown]` + Details about the pending safety check. - A JSON schema object describing the parameters of the function. + - `status: "in_progress" or "completed" or "incomplete"` - - `strict: boolean` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Whether strict parameter validation is enforced for this function tool. + - `"in_progress"` - - `type: "function"` + - `"completed"` - The type of the function tool. Always `function`. + - `"incomplete"` - - `"function"` + - `type: "computer_call"` - - `allowed_callers: optional array of "direct" or "programmatic"` + The type of the computer call. Always `computer_call`. - The tool invocation context(s). + - `"computer_call"` - - `"direct"` + - `action: optional BetaComputerAction` - - `"programmatic"` + A click action. - - `defer_loading: optional boolean` + - `Click object { button, type, x, 2 more }` - Whether this function is deferred and loaded via tool search. + A click action. - - `description: optional string` + - `button: "left" or "right" or "wheel" or 2 more` - A description of the function. Used by the model to determine whether or not to call the function. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `output_schema: optional map[unknown]` + - `"left"` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `"right"` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `"wheel"` - 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). + - `"back"` - - `type: "file_search"` + - `"forward"` - The type of the file search tool. Always `file_search`. + - `type: "click"` - - `"file_search"` + Specifies the event type. For a click action, this property is always `click`. - - `vector_store_ids: array of string` + - `"click"` - The IDs of the vector stores to search. + - `x: number` - - `filters: optional object { key, type, value } or object { filters, type }` + The x-coordinate where the click occurred. - A filter to apply. + - `y: number` - - `ComparisonFilter object { key, type, value }` + The y-coordinate where the click occurred. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `keys: optional array of string` - - `key: string` + The keys being held while clicking. - The key to compare against the value. + - `DoubleClick object { keys, type, x, y }` - - `type: "eq" or "ne" or "gt" or 5 more` + A double click action. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `keys: array of string` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + The keys being held while double-clicking. - - `"eq"` + - `type: "double_click"` - - `"ne"` + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `"gt"` + - `"double_click"` - - `"gte"` + - `x: number` - - `"lt"` + The x-coordinate where the double click occurred. - - `"lte"` + - `y: number` - - `"in"` + The y-coordinate where the double click occurred. - - `"nin"` + - `Drag object { path, type, keys }` - - `value: string or number or boolean or array of string or number` + A drag action. - The value to compare against the attribute key; supports string, number, or boolean types. + - `path: array of object { x, y }` - - `string` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `number` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` + + - `x: number` + + The x-coordinate. + + - `y: number` + + The y-coordinate. + + - `type: "drag"` + + Specifies the event type. For a drag action, this property is always set to `drag`. + + - `"drag"` + + - `keys: optional array of string` + + The keys being held while dragging the mouse. + + - `Keypress object { keys, type }` + + A collection of keypresses the model would like to perform. + + - `keys: array of string` + + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + + - `type: "keypress"` + + Specifies the event type. For a keypress action, this property is always set to `keypress`. + + - `"keypress"` + + - `Move object { type, x, y, keys }` + + A mouse move action. + + - `type: "move"` + + Specifies the event type. For a move action, this property is always set to `move`. + + - `"move"` + + - `x: number` + + The x-coordinate to move to. + + - `y: number` + + The y-coordinate to move to. + + - `keys: optional array of string` + + The keys being held while moving the mouse. + + - `Screenshot object { type }` + + A screenshot action. + + - `type: "screenshot"` + + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + + - `"screenshot"` + + - `Scroll object { scroll_x, scroll_y, type, 3 more }` + + A scroll action. + + - `scroll_x: number` + + The horizontal scroll distance. + + - `scroll_y: number` + + The vertical scroll distance. + + - `type: "scroll"` + + Specifies the event type. For a scroll action, this property is always set to `scroll`. + + - `"scroll"` + + - `x: number` + + The x-coordinate where the scroll occurred. + + - `y: number` + + The y-coordinate where the scroll occurred. + + - `keys: optional array of string` + + The keys being held while scrolling. + + - `Type object { text, type }` + + An action to type in text. + + - `text: string` + + The text to type. + + - `type: "type"` + + Specifies the event type. For a type action, this property is always set to `type`. + + - `"type"` + + - `Wait object { type }` + + A wait action. + + - `type: "wait"` + + Specifies the event type. For a wait action, this property is always set to `wait`. + + - `"wait"` + + - `actions: optional BetaComputerActionList` + + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. + + - `Click object { button, type, x, 2 more }` + + A click action. + + - `DoubleClick object { keys, type, x, y }` + + A double click action. + + - `Drag object { path, type, keys }` + + A drag action. + + - `Keypress object { keys, type }` + + A collection of keypresses the model would like to perform. + + - `Move object { type, x, y, keys }` + + A mouse move action. + + - `Screenshot object { type }` + + A screenshot action. + + - `Scroll object { scroll_x, scroll_y, type, 3 more }` + + A scroll action. + + - `Type object { text, type }` + + An action to type in text. + + - `Wait object { type }` + + A wait action. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `ComputerCallOutput object { call_id, output, type, 4 more }` + + The output of a computer tool call. + + - `call_id: string` + + The ID of the computer tool call that produced the output. + + - `output: BetaResponseComputerToolCallOutputScreenshot` + + A computer screenshot image used with the computer use tool. + + - `type: "computer_screenshot"` + + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. + + - `"computer_screenshot"` + + - `file_id: optional string` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: optional string` + + The URL of the screenshot image. + + - `type: "computer_call_output"` + + The type of the computer tool call output. Always `computer_call_output`. + + - `"computer_call_output"` + + - `id: optional string` + + The ID of the computer tool call output. + + - `acknowledged_safety_checks: optional array of object { id, code, message }` + + The safety checks reported by the API that have been acknowledged by the developer. + + - `id: string` + + The ID of the pending safety check. + + - `code: optional string` + + The type of the pending safety check. + + - `message: optional string` + + Details about the pending safety check. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `WebSearchCall object { id, action, status, 2 more }` + + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. + + - `id: string` + + The unique ID of the web search tool call. + + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). + + - `Search object { type, queries, query, sources }` + + Action type "search" - Performs a web search query. + + - `type: "search"` + + The action type. + + - `"search"` + + - `queries: optional array of string` + + The search queries. + + - `query: optional string` + + The search query. + + - `sources: optional array of object { type, url }` + + The sources used in the search. + + - `type: "url"` + + The type of source. Always `url`. + + - `"url"` + + - `url: string` + + The URL of the source. + + - `OpenPage object { type, url }` + + Action type "open_page" - Opens a specific URL from search results. + + - `type: "open_page"` + + The action type. + + - `"open_page"` + + - `url: optional string` + + The URL opened by the model. + + - `FindInPage object { pattern, type, url }` + + Action type "find_in_page": Searches for a pattern within a loaded page. + + - `pattern: string` + + The pattern or text to search for within the page. + + - `type: "find_in_page"` + + The action type. + + - `"find_in_page"` + + - `url: string` + + The URL of the page searched for the pattern. + + - `status: "in_progress" or "searching" or "completed" or "failed"` + + The status of the web search tool call. + + - `"in_progress"` + + - `"searching"` + + - `"completed"` + + - `"failed"` + + - `type: "web_search_call"` + + The type of the web search tool call. Always `web_search_call`. + + - `"web_search_call"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `FunctionCall object { arguments, call_id, name, 6 more }` + + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. + + - `arguments: string` + + A JSON string of the arguments to pass to the function. + + - `call_id: string` + + The unique ID of the function tool call generated by the model. + + - `name: string` + + The name of the function to run. + + - `type: "function_call"` + + The type of the function tool call. Always `function_call`. + + - `"function_call"` + + - `id: optional string` + + The unique ID of the function tool call. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + + - `namespace: optional string` + + The namespace of the function to run. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `FunctionCallOutput object { call_id, output, type, 4 more }` + + The output of a function tool call. + + - `call_id: string` + + The unique ID of the function tool call generated by the model. + + - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` + + Text, image, or file output of the function tool call. + + - `string` + + A JSON string of the output of the function tool call. + + - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` + + An array of content outputs (text, image, file) for the function tool call. + + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `"input_text"` + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](/docs/guides/vision) + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `"input_image"` + + - `detail: optional "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `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"` + + - `BetaResponseInputFileContent 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. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `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"` + + - `AgentMessage object { author, content, recipient, 3 more }` + + A message routed between agents. + + - `author: string` + + The sending agent identity. + + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` + + Plaintext, image, or encrypted content sent between agents. + + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](/docs/guides/vision) + + - `EncryptedContent object { encrypted_content, type }` + + Opaque encrypted content that Responses API decrypts inside trusted model execution. + + - `encrypted_content: string` + + Opaque encrypted content. + + - `type: "encrypted_content"` + + The type of the input item. Always `encrypted_content`. + + - `"encrypted_content"` + + - `recipient: string` + + The destination agent identity. + + - `type: "agent_message"` + + The item type. Always `agent_message`. + + - `"agent_message"` + + - `id: optional string` + + The unique ID of this agent message item. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `MultiAgentCall object { action, arguments, call_id, 3 more }` + + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + + The multi-agent action that was executed. + + - `"spawn_agent"` + + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` + + - `arguments: string` + + The action arguments as a JSON string. + + - `call_id: string` + + The unique ID linking this call to its output. + + - `type: "multi_agent_call"` + + The item type. Always `multi_agent_call`. + + - `"multi_agent_call"` + + - `id: optional string` + + The unique ID of this multi-agent call. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `MultiAgentCallOutput object { action, call_id, output, 3 more }` + + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + + The multi-agent action that produced this result. + + - `"spawn_agent"` + + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` + + - `call_id: string` + + The unique ID of the multi-agent call. + + - `output: array of object { text, type, annotations }` + + Text output returned by the multi-agent action. + + - `text: string` + + The text content. + + - `type: "output_text"` + + The content type. Always `output_text`. + + - `"output_text"` + + - `annotations: optional 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 }` + + Citations associated with the text content. + + - `FileCitation object { file_id, filename, index, type }` + + - `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 citation type. Always `file_citation`. + + - `"file_citation"` + + - `URLCitation object { end_index, start_index, title, 2 more }` + + - `end_index: number` + + The index of the last character of the citation in the message. + + - `start_index: number` + + The index of the first character of the citation in the message. + + - `title: string` + + The title of the cited resource. + + - `type: "url_citation"` + + The citation type. Always `url_citation`. + + - `"url_citation"` + + - `url: string` + + The URL of the cited resource. + + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + + - `container_id: string` + + The ID of the container. + + - `end_index: number` + + The index of the last character of the citation in the message. + + - `file_id: string` + + The ID of the container file. + + - `filename: string` + + The filename of the container file cited. + + - `start_index: number` + + The index of the first character of the citation in the message. + + - `type: "container_file_citation"` + + The citation type. Always `container_file_citation`. + + - `"container_file_citation"` + + - `type: "multi_agent_call_output"` + + The item type. Always `multi_agent_call_output`. + + - `"multi_agent_call_output"` + + - `id: optional string` + + The unique ID of this multi-agent call output. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `ToolSearchCall object { arguments, type, id, 4 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. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `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, 4 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 object { key, type, value } or object { filters, type }` + + 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` @@ -17445,17 +19075,9 @@ as input for the model's response. ### 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" - }' +curl https://api.openai.com/v1/responses/$RESPONSE_ID/cancel \ + -X POST \ + -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response @@ -17633,42 +19255,39 @@ curl https://api.openai.com/v1/responses \ } ``` -### Text input +### Example ```http -curl https://api.openai.com/v1/responses \ +curl -X POST https://api.openai.com/v1/responses/resp_123/cancel \ -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." - }' + -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { - "id": "resp_67ccd2bed1ec8190b14f964abc0542670bb6a6b452d3795b", + "id": "resp_67cb71b351908190a308f3859487620d06981a8637e6bc44", "object": "response", - "created_at": 1741476542, - "status": "completed", - "completed_at": 1741476543, + "created_at": 1741386163, + "status": "cancelled", + "background": true, + "completed_at": null, "error": null, "incomplete_details": null, "instructions": null, "max_output_tokens": null, - "model": "gpt-5.4", + "model": "gpt-4o-2024-08-06", "output": [ { "type": "message", - "id": "msg_67ccd2bf17f0819081ff3bb2cf6508e60bb6a6b452d3795b", - "status": "completed", + "id": "msg_67cb71b3c2b0819084d481baaaf148f206981a8637e6bc44", + "status": "in_progress", "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.", + "text": "Silent circuits hum, \nThoughts emerge in data streams— \nDigital dawn breaks.", "annotations": [] } ] @@ -17691,863 +19310,239 @@ curl https://api.openai.com/v1/responses \ "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 - }, + "usage": null, "user": null, "metadata": {} } ``` -### Image input +## Compact a response -```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" - } - ] - } - ] - }' -``` +**post** `/responses/compact?beta=true` -#### Response +Compact a conversation. Returns a compacted response object. -```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": {} -} -``` +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). -### File input +### Header Parameters -```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" - } - ] - } - ] - }' -``` +- `"openai-beta": optional array of "responses_multi_agent=v1"` -#### Response + - `"responses_multi_agent=v1"` -```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": {} -} -``` +### Body Parameters -### Web search +- `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` -```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?" - }' -``` + 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. -#### Response + - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 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": {} -} -``` + 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. -### File search + - `"gpt-5.6-sol"` -```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?" - }' -``` + - `"gpt-5.6-terra"` -#### Response + - `"gpt-5.6-luna"` -```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": {} -} -``` + - `"gpt-5.4"` -### Streaming + - `"gpt-5.4-mini"` -```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 - }' -``` + - `"gpt-5.4-nano"` -#### Response + - `"gpt-5.4-mini-2026-03-17"` -```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":{}}} + - `"gpt-5.4-nano-2026-03-17"` -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":{}}} + - `"gpt-5.3-chat-latest"` -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":[]}} + - `"gpt-5.2"` -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":[]}} + - `"gpt-5.2-2025-12-11"` -event: response.output_text.delta -data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"Hi"} + - `"gpt-5.2-chat-latest"` -... + - `"gpt-5.2-pro"` -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?"} + - `"gpt-5.2-pro-2025-12-11"` -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":[]}} + - `"gpt-5.1"` -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":[]}]}} + - `"gpt-5.1-2025-11-13"` -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":{}}} -``` + - `"gpt-5.1-codex"` -### Functions + - `"gpt-5.1-mini"` -```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" - }' -``` + - `"gpt-5.1-chat-latest"` -#### Response + - `"gpt-5"` -```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": {} -} -``` + - `"gpt-5-mini"` -### Reasoning + - `"gpt-5-nano"` -```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" - } - }' -``` + - `"gpt-5-2025-08-07"` -#### Response + - `"gpt-5-mini-2025-08-07"` -```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": {} -} -``` + - `"gpt-5-nano-2025-08-07"` -## Get a model response + - `"gpt-5-chat-latest"` -**get** `/responses/{response_id}?beta=true` + - `"gpt-4.1"` -Retrieves a model response with the given ID. + - `"gpt-4.1-mini"` -### Path Parameters + - `"gpt-4.1-nano"` -- `response_id: string` + - `"gpt-4.1-2025-04-14"` -### Query Parameters + - `"gpt-4.1-mini-2025-04-14"` -- `include: optional array of BetaResponseIncludable` + - `"gpt-4.1-nano-2025-04-14"` - Additional fields to include in the response. See the `include` - parameter for Response creation above for more information. + - `"o4-mini"` - - `"file_search_call.results"` + - `"o4-mini-2025-04-16"` - - `"web_search_call.results"` + - `"o3"` - - `"web_search_call.action.sources"` + - `"o3-2025-04-16"` - - `"message.input_image.image_url"` + - `"o3-mini"` - - `"computer_call_output.output.image_url"` + - `"o3-mini-2025-01-31"` - - `"code_interpreter_call.outputs"` + - `"o1"` - - `"reasoning.encrypted_content"` + - `"o1-2024-12-17"` - - `"message.output_text.logprobs"` + - `"o1-preview"` -- `include_obfuscation: optional boolean` + - `"o1-preview-2024-09-12"` - 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. + - `"o1-mini"` -- `starting_after: optional number` + - `"o1-mini-2024-09-12"` - The sequence number of the event after which to start streaming. + - `"gpt-4o"` -- `stream: optional false` + - `"gpt-4o-2024-11-20"` - 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. + - `"gpt-4o-2024-08-06"` - - `false` + - `"gpt-4o-2024-05-13"` -### Header Parameters + - `"gpt-4o-audio-preview"` -- `"openai-beta": optional array of "responses_multi_agent=v1"` + - `"gpt-4o-audio-preview-2024-10-01"` - - `"responses_multi_agent=v1"` + - `"gpt-4o-audio-preview-2024-12-17"` -### Returns + - `"gpt-4o-audio-preview-2025-06-03"` -- `BetaResponse object { id, created_at, error, 32 more }` + - `"gpt-4o-mini-audio-preview"` - - `id: string` + - `"gpt-4o-mini-audio-preview-2024-12-17"` - Unique identifier for this Response. + - `"gpt-4o-search-preview"` - - `created_at: number` + - `"gpt-4o-mini-search-preview"` - Unix timestamp (in seconds) of when this Response was created. + - `"gpt-4o-search-preview-2025-03-11"` - - `error: BetaResponseError` + - `"gpt-4o-mini-search-preview-2025-03-11"` - An error object returned when the model fails to generate a Response. + - `"chatgpt-4o-latest"` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 17 more` + - `"codex-mini-latest"` - The error code for the response. + - `"gpt-4o-mini"` - - `"server_error"` + - `"gpt-4o-mini-2024-07-18"` - - `"rate_limit_exceeded"` + - `"gpt-4-turbo"` - - `"invalid_prompt"` + - `"gpt-4-turbo-2024-04-09"` - - `"data_residency_mismatch"` + - `"gpt-4-0125-preview"` - - `"bio_policy"` + - `"gpt-4-turbo-preview"` - - `"vector_store_timeout"` + - `"gpt-4-1106-preview"` - - `"invalid_image"` + - `"gpt-4-vision-preview"` - - `"invalid_image_format"` + - `"gpt-4"` - - `"invalid_base64_image"` + - `"gpt-4-0314"` - - `"invalid_image_url"` + - `"gpt-4-0613"` - - `"image_too_large"` + - `"gpt-4-32k"` - - `"image_too_small"` + - `"gpt-4-32k-0314"` - - `"image_parse_error"` + - `"gpt-4-32k-0613"` - - `"image_content_policy_violation"` + - `"gpt-3.5-turbo"` - - `"invalid_image_mode"` + - `"gpt-3.5-turbo-16k"` - - `"image_file_too_large"` + - `"gpt-3.5-turbo-0301"` - - `"unsupported_image_media_type"` + - `"gpt-3.5-turbo-0613"` - - `"empty_image_file"` + - `"gpt-3.5-turbo-1106"` - - `"failed_to_download_image"` + - `"gpt-3.5-turbo-0125"` - - `"image_file_not_found"` + - `"gpt-3.5-turbo-16k-0613"` - - `message: string` + - `"o1-pro"` - A human-readable description of the error. + - `"o1-pro-2025-03-19"` - - `incomplete_details: object { reason }` + - `"o3-pro"` - Details about why the response is incomplete. + - `"o3-pro-2025-06-10"` - - `reason: optional "max_output_tokens" or "content_filter"` + - `"o3-deep-research"` - The reason why the response is incomplete. + - `"o3-deep-research-2025-06-26"` - - `"max_output_tokens"` + - `"o4-mini-deep-research"` - - `"content_filter"` + - `"o4-mini-deep-research-2025-06-26"` - - `instructions: string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + - `"computer-use-preview"` - A system (or developer) message inserted into the model's context. + - `"computer-use-preview-2025-03-11"` - 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. + - `"gpt-5-codex"` + + - `"gpt-5-pro"` + + - `"gpt-5-pro-2025-10-06"` + + - `"gpt-5.1-codex-max"` - `string` - A text input to the model, equivalent to a text input with the - `developer` role. +- `input: optional string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + Text, image, or file inputs to the model, used to generate a response - A list of one or many input items to the model, containing - different content types. + - `string` + + A text input to the model, equivalent to a text input with the `user` role. + + - `array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + + A list of one or many input items to the model, containing different content types. - `BetaEasyInputMessage object { content, role, phase, type }` @@ -23321,497 +24316,244 @@ Retrieves a model response with the given ID. The canonical name of the agent that produced this item. - - `metadata: map[string]` - - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. - - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. - - - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - - Model ID used to generate the response, like `gpt-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. - - - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` - - Model ID used to generate the response, like `gpt-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. - - - `"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"` - - - `"gpt-5.2"` - - - `"gpt-5.2-2025-12-11"` - - - `"gpt-5.2-chat-latest"` - - - `"gpt-5.2-pro"` - - - `"gpt-5.2-pro-2025-12-11"` - - - `"gpt-5.1"` - - - `"gpt-5.1-2025-11-13"` - - - `"gpt-5.1-codex"` - - - `"gpt-5.1-mini"` - - - `"gpt-5.1-chat-latest"` - - - `"gpt-5"` - - - `"gpt-5-mini"` - - - `"gpt-5-nano"` - - - `"gpt-5-2025-08-07"` - - - `"gpt-5-mini-2025-08-07"` - - - `"gpt-5-nano-2025-08-07"` - - - `"gpt-5-chat-latest"` - - - `"gpt-4.1"` - - - `"gpt-4.1-mini"` - - - `"gpt-4.1-nano"` - - - `"gpt-4.1-2025-04-14"` - - - `"gpt-4.1-mini-2025-04-14"` - - - `"gpt-4.1-nano-2025-04-14"` - - - `"o4-mini"` - - - `"o4-mini-2025-04-16"` - - - `"o3"` - - - `"o3-2025-04-16"` - - - `"o3-mini"` - - - `"o3-mini-2025-01-31"` - - - `"o1"` - - - `"o1-2024-12-17"` - - - `"o1-preview"` - - - `"o1-preview-2024-09-12"` - - - `"o1-mini"` - - - `"o1-mini-2024-09-12"` - - - `"gpt-4o"` - - - `"gpt-4o-2024-11-20"` - - - `"gpt-4o-2024-08-06"` - - - `"gpt-4o-2024-05-13"` - - - `"gpt-4o-audio-preview"` - - - `"gpt-4o-audio-preview-2024-10-01"` - - - `"gpt-4o-audio-preview-2024-12-17"` - - - `"gpt-4o-audio-preview-2025-06-03"` - - - `"gpt-4o-mini-audio-preview"` - - - `"gpt-4o-mini-audio-preview-2024-12-17"` - - - `"gpt-4o-search-preview"` - - - `"gpt-4o-mini-search-preview"` - - - `"gpt-4o-search-preview-2025-03-11"` - - - `"gpt-4o-mini-search-preview-2025-03-11"` - - - `"chatgpt-4o-latest"` - - - `"codex-mini-latest"` - - - `"gpt-4o-mini"` - - - `"gpt-4o-mini-2024-07-18"` - - - `"gpt-4-turbo"` - - - `"gpt-4-turbo-2024-04-09"` - - - `"gpt-4-0125-preview"` - - - `"gpt-4-turbo-preview"` - - - `"gpt-4-1106-preview"` - - - `"gpt-4-vision-preview"` - - - `"gpt-4"` - - - `"gpt-4-0314"` - - - `"gpt-4-0613"` - - - `"gpt-4-32k"` - - - `"gpt-4-32k-0314"` - - - `"gpt-4-32k-0613"` - - - `"gpt-3.5-turbo"` - - - `"gpt-3.5-turbo-16k"` - - - `"gpt-3.5-turbo-0301"` - - - `"gpt-3.5-turbo-0613"` - - - `"gpt-3.5-turbo-1106"` - - - `"gpt-3.5-turbo-0125"` +- `instructions: optional string` - - `"gpt-3.5-turbo-16k-0613"` + 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. - - `"o1-pro"` +- `previous_response_id: optional string` - - `"o1-pro-2025-03-19"` + 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`. - - `"o3-pro"` +- `prompt_cache_key: optional string` - - `"o3-pro-2025-06-10"` + A key to use when reading from or writing to the prompt cache. - - `"o3-deep-research"` +- `prompt_cache_options: optional object { mode, ttl }` - - `"o3-deep-research-2025-06-26"` + 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. - - `"o4-mini-deep-research"` + - `mode: optional "implicit" or "explicit"` - - `"o4-mini-deep-research-2025-06-26"` + 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. - - `"computer-use-preview"` + - `"implicit"` - - `"computer-use-preview-2025-03-11"` + - `"explicit"` - - `"gpt-5-codex"` + - `ttl: optional "30m"` - - `"gpt-5-pro"` + 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. - - `"gpt-5-pro-2025-10-06"` + - `"30m"` - - `"gpt-5.1-codex-max"` +- `prompt_cache_retention: optional "in_memory" or "24h"` - - `string` + How long to retain a prompt cache entry created by this request. - - `object: "response"` + - `"in_memory"` - The object type of this resource - always set to `response`. + - `"24h"` - - `"response"` +- `service_tier: optional "auto" or "default" or "flex" or "priority"` - - `output: array of BetaResponseOutputItem` + The service tier to use for this request. - An array of content items generated by the model. + - `"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. + - `"default"` - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + - `"flex"` - An output message from the model. + - `"priority"` - - `FileSearchCall object { id, queries, status, 3 more }` +### Returns - The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. +- `BetaCompactedResponse object { id, created_at, object, 2 more }` - `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"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `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. + The unique identifier for the compacted response. - - `text: optional string` + - `created_at: number` - The text that was retrieved from the file. + Unix timestamp (in seconds) when the compacted conversation was created. - - `FunctionCall object { arguments, call_id, name, 6 more }` + - `object: "response.compaction"` - A tool call to run a function. See the - [function calling guide](/docs/guides/function-calling) for more information. + The object type. Always `response.compaction`. - - `arguments: string` + - `"response.compaction"` - A JSON string of the arguments to pass to the function. + - `output: array of object { id, content, role, 4 more } or object { id, call_id, code, 3 more } or object { id, call_id, result, 3 more } or 28 more` - - `call_id: string` + The compacted list of output items. - The unique ID of the function tool call generated by the model. + - `Message object { id, content, role, 4 more }` - - `name: string` + A message to or from the model. - The name of the function to run. + - `id: string` - - `type: "function_call"` + The unique ID of the message. - The type of the function tool call. Always `function_call`. + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - - `"function_call"` + The content of the message - - `id: optional string` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - The unique ID of the function tool call. + A text input to the model. - - `agent: optional object { agent_name }` + - `text: string` - The agent that produced this item. + The text input to the model. - - `agent_name: string` + - `type: "input_text"` - The canonical name of the agent that produced this item. + The type of the input item. Always `input_text`. - - `caller: optional object { type } or object { caller_id, type }` + - `"input_text"` - The execution context that produced this tool call. + - `prompt_cache_breakpoint: optional object { mode }` - - `Direct object { 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. - - `type: "direct"` + - `mode: "explicit"` - - `"direct"` + The breakpoint mode. Always `explicit`. - - `Program object { caller_id, type }` + - `"explicit"` - - `caller_id: string` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - The call ID of the program item that produced this tool call. + A text output from the model. - - `type: "program"` + - `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 }` - - `"program"` + The annotations of the text output. - - `namespace: optional string` + - `FileCitation object { file_id, filename, index, type }` - The namespace of the function to run. + A citation to a file. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `file_id: string` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The ID of the file. - - `"in_progress"` + - `filename: string` - - `"completed"` + The filename of the file cited. - - `"incomplete"` + - `index: number` - - `FunctionCallOutput object { id, call_id, output, 5 more }` + The index of the file in the list of files. - - `id: string` + - `type: "file_citation"` - The unique ID of the function call tool output. + The type of the file citation. Always `file_citation`. - - `call_id: string` + - `"file_citation"` - The unique ID of the function tool call generated by the model. + - `URLCitation object { end_index, start_index, title, 2 more }` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + A citation for a web resource used to generate a model response. - The output from the function call generated by your code. - Can be a string or an list of output content. + - `end_index: number` - - `StringOutput = string` + The index of the last character of the URL citation in the message. - A string of the output of the function call. + - `start_index: number` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The index of the first character of the URL citation in the message. - Text, image, or file output of the function call. + - `title: string` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + The title of the web resource. - A text input to the model. + - `type: "url_citation"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + The type of the URL citation. Always `url_citation`. - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `"url_citation"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `url: string` - A file input to the model. + The URL of the web resource. - - `status: "in_progress" or "completed" or "incomplete"` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + A citation for a container file used to generate a model response. - - `"in_progress"` + - `container_id: string` - - `"completed"` + The ID of the container file. - - `"incomplete"` + - `end_index: number` - - `type: "function_call_output"` + The index of the last character of the container file citation in the message. - The type of the function tool call output. Always `function_call_output`. + - `file_id: string` - - `"function_call_output"` + The ID of the file. - - `agent: optional object { agent_name }` + - `filename: string` - The agent that produced this item. + The filename of the container file cited. - - `agent_name: string` + - `start_index: number` - The canonical name of the agent that produced this item. + The index of the first character of the container file citation in the message. - - `caller: optional object { type } or object { caller_id, type }` + - `type: "container_file_citation"` - The execution context that produced this tool call. + The type of the container file citation. Always `container_file_citation`. - - `Direct object { type }` + - `"container_file_citation"` - - `type: "direct"` + - `FilePath object { file_id, index, type }` - The caller type. Always `direct`. + A path to a file. - - `"direct"` + - `file_id: string` - - `Program object { caller_id, type }` + The ID of the file. - - `caller_id: string` + - `index: number` - The call ID of the program item that produced this tool call. + The index of the file in the list of files. - - `type: "program"` + - `type: "file_path"` - The caller type. Always `program`. + The type of the file path. Always `file_path`. - - `"program"` + - `"file_path"` - - `created_by: optional string` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - The identifier of the actor that created the item. + - `token: string` - - `AgentMessage object { id, author, content, 3 more }` + - `bytes: array of number` - - `id: string` + - `logprob: number` - The unique ID of the agent message. + - `top_logprobs: array of object { token, bytes, logprob }` - - `author: string` + - `token: string` - The sending agent identity. + - `bytes: array of number` - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + - `logprob: number` - Encrypted content sent between agents. + - `text: string` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + The text output from the model. - A text input to the model. + - `type: "output_text"` - - `BetaResponseOutputText object { annotations, logprobs, text, type }` + The type of the output text. Always `output_text`. - A text output from the model. + - `"output_text"` - `Text object { text, type }` @@ -23855,17 +24597,23 @@ Retrieves a model response with the given ID. A refusal from the model. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `refusal: string` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + The refusal explanation from the model. - - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` + - `type: "refusal"` - A screenshot of a computer. + The type of the refusal. Always `refusal`. + + - `"refusal"` + + - `BetaResponseInputImage 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 screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - `"low"` @@ -23875,19 +24623,19 @@ Retrieves a model response with the given ID. - `"original"` - - `file_id: string` + - `type: "input_image"` - The identifier of an uploaded file that contains the screenshot. + The type of the input item. Always `input_image`. - - `image_url: string` + - `"input_image"` - The URL of the screenshot image. + - `file_id: optional string` - - `type: "computer_screenshot"` + The ID of the file to be sent to the model. - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `image_url: optional string` - - `"computer_screenshot"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - `prompt_cache_breakpoint: optional object { mode }` @@ -23899,135 +24647,141 @@ Retrieves a model response with the given ID. - `"explicit"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` - A file input to the model. + A screenshot of a computer. - - `EncryptedContent object { encrypted_content, type }` + - `detail: "low" or "high" or "auto" or "original"` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `encrypted_content: string` + - `"low"` - Opaque encrypted content. + - `"high"` - - `type: "encrypted_content"` + - `"auto"` - The type of the input item. Always `encrypted_content`. + - `"original"` - - `"encrypted_content"` + - `file_id: string` - - `recipient: string` + The identifier of an uploaded file that contains the screenshot. - The destination agent identity. + - `image_url: string` - - `type: "agent_message"` + The URL of the screenshot image. - The type of the item. Always `agent_message`. + - `type: "computer_screenshot"` - - `"agent_message"` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `agent: optional object { agent_name }` + - `"computer_screenshot"` - The agent that produced this item. + - `prompt_cache_breakpoint: optional object { mode }` - - `agent_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 canonical name of the agent that produced this item. + - `mode: "explicit"` - - `MultiAgentCall object { id, action, arguments, 3 more }` + The breakpoint mode. Always `explicit`. - - `id: string` + - `"explicit"` - The unique ID of the multi-agent call item. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + A file input to the model. - The multi-agent action to execute. + - `type: "input_file"` - - `"spawn_agent"` + The type of the input item. Always `input_file`. - - `"interrupt_agent"` + - `"input_file"` - - `"list_agents"` + - `detail: optional "auto" or "low" or "high"` - - `"send_message"` + 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`. - - `"followup_task"` + - `"auto"` - - `"wait_agent"` + - `"low"` - - `arguments: string` + - `"high"` - The JSON string of arguments generated for the action. + - `file_data: optional string` - - `call_id: string` + The content of the file to be sent to the model. - The unique ID linking this call to its output. + - `file_id: optional string` - - `type: "multi_agent_call"` + The ID of the file to be sent to the model. - The type of the multi-agent call. Always `multi_agent_call`. + - `file_url: optional string` - - `"multi_agent_call"` + The URL of the file to be sent to the model. - - `agent: optional object { agent_name }` + - `filename: optional string` - The agent that produced this item. + The name of the file to be sent to the model. - - `agent_name: string` + - `prompt_cache_breakpoint: optional object { mode }` - The canonical name of the agent that produced this item. + 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. - - `MultiAgentCallOutput object { id, action, call_id, 3 more }` + - `mode: "explicit"` - - `id: string` + The breakpoint mode. Always `explicit`. - The unique ID of the multi-agent call output item. + - `"explicit"` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `EncryptedContent object { encrypted_content, type }` - The multi-agent action that produced this result. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `"spawn_agent"` + - `encrypted_content: string` - - `"interrupt_agent"` + Opaque encrypted content. - - `"list_agents"` + - `type: "encrypted_content"` - - `"send_message"` + The type of the input item. Always `encrypted_content`. - - `"followup_task"` + - `"encrypted_content"` - - `"wait_agent"` + - `role: "unknown" or "user" or "assistant" or 5 more` - - `call_id: string` + The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. - The unique ID of the multi-agent call. + - `"unknown"` - - `output: array of BetaResponseOutputText` + - `"user"` - Text output returned by the multi-agent action. + - `"assistant"` - - `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 }` + - `"system"` - The annotations of the text output. + - `"critic"` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `"discriminator"` - - `text: string` + - `"developer"` - The text output from the model. + - `"tool"` - - `type: "output_text"` + - `status: "in_progress" or "completed" or "incomplete"` - The type of the output text. Always `output_text`. + The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `type: "multi_agent_call_output"` + - `"in_progress"` - The type of the multi-agent result. Always `multi_agent_call_output`. + - `"completed"` - - `"multi_agent_call_output"` + - `"incomplete"` + + - `type: "message"` + + The type of the message. Always set to `message`. + + - `"message"` - `agent: optional object { agent_name }` @@ -24037,101 +24791,37 @@ Retrieves a model response with the given ID. The canonical name of the agent that produced this item. - - `WebSearchCall object { id, action, status, 2 more }` - - The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. - - - `id: string` - - The unique ID of the web search tool call. - - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). - - - `Search object { type, queries, query, sources }` - - Action type "search" - Performs a web search query. - - - `type: "search"` - - The action type. - - - `"search"` - - - `queries: optional array of string` - - The search queries. - - - `query: optional string` - - The search query. - - - `sources: optional array of object { type, url }` - - The sources used in the search. - - - `type: "url"` - - The type of source. Always `url`. - - - `"url"` - - - `url: string` - - The URL of the source. - - - `OpenPage object { type, url }` - - Action type "open_page" - Opens a specific URL from search results. - - - `type: "open_page"` - - The action type. - - - `"open_page"` - - - `url: optional string` - - The URL opened by the model. - - - `FindInPage object { pattern, type, url }` - - Action type "find_in_page": Searches for a pattern within a loaded page. - - - `pattern: string` + - `phase: optional "commentary" or "final_answer"` - The pattern or text to search for within the page. + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `type: "find_in_page"` + - `"commentary"` - The action type. + - `"final_answer"` - - `"find_in_page"` + - `Program object { id, call_id, code, 3 more }` - - `url: string` + - `id: string` - The URL of the page searched for the pattern. + The unique ID of the program item. - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `call_id: string` - The status of the web search tool call. + The stable call ID of the program item. - - `"in_progress"` + - `code: string` - - `"searching"` + The JavaScript source executed by programmatic tool calling. - - `"completed"` + - `fingerprint: string` - - `"failed"` + Opaque program replay fingerprint that must be round-tripped. - - `type: "web_search_call"` + - `type: "program"` - The type of the web search tool call. Always `web_search_call`. + The type of the item. Always `program`. - - `"web_search_call"` + - `"program"` - `agent: optional object { agent_name }` @@ -24141,60 +24831,33 @@ Retrieves a model response with the given ID. The canonical name of the agent that produced this item. - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + - `ProgramOutput object { id, call_id, result, 3 more }` - `id: string` - The unique ID of the computer call. + The unique ID of the program output item. - `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` + The call ID of the program item. - Details about the pending safety check. + - `result: string` - - `status: "in_progress" or "completed" or "incomplete"` + The result produced by the program item. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `status: "completed" or "incomplete"` - - `"in_progress"` + The terminal status of the program output item. - `"completed"` - `"incomplete"` - - `type: "computer_call"` - - The type of the computer call. Always `computer_call`. - - - `"computer_call"` - - - `action: optional BetaComputerAction` - - A click action. + - `type: "program_output"` - - `actions: optional BetaComputerActionList` + The type of the item. Always `program_output`. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `"program_output"` - `agent: optional object { agent_name }` @@ -24204,55 +24867,32 @@ Retrieves a model response with the given ID. The canonical name of the agent that produced this item. - - `ComputerCallOutput object { id, call_id, output, 5 more }` - - - `id: string` - - The unique ID of the computer call tool output. - - - `call_id: string` - - The ID of the computer tool call that produced the output. - - - `output: BetaResponseComputerToolCallOutputScreenshot` - - A computer screenshot image used with the computer use tool. - - - `status: "completed" or "incomplete" or "failed" or "in_progress"` - - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. - - - `"completed"` - - - `"incomplete"` - - - `"failed"` + - `FunctionCall object { arguments, call_id, name, 6 more }` - - `"in_progress"` + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `type: "computer_call_output"` + - `arguments: string` - The type of the computer tool call output. Always `computer_call_output`. + A JSON string of the arguments to pass to the function. - - `"computer_call_output"` + - `call_id: string` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + The unique ID of the function tool call generated by the model. - The safety checks reported by the API that have been acknowledged by the - developer. + - `name: string` - - `id: string` + The name of the function to run. - The ID of the pending safety check. + - `type: "function_call"` - - `code: optional string` + The type of the function tool call. Always `function_call`. - The type of the pending safety check. + - `"function_call"` - - `message: optional string` + - `id: optional string` - Details about the pending safety check. + The unique ID of the function tool call. - `agent: optional object { agent_name }` @@ -24262,139 +24902,134 @@ Retrieves a model response with the given ID. The canonical name of the agent that produced this item. - - `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. - - `Reasoning object { id, summary, type, 4 more }` + - `Direct object { type }` - 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: "direct"` - - `id: string` + - `"direct"` - The unique identifier of the reasoning content. + - `Program object { caller_id, type }` - - `summary: array of object { text, type }` + - `caller_id: string` - Reasoning summary content. + The call ID of the program item that produced this tool call. - - `text: string` + - `type: "program"` - A summary of the reasoning output from the model so far. + - `"program"` - - `type: "summary_text"` + - `namespace: optional string` - The type of the object. Always `summary_text`. + The namespace of the function to run. - - `"summary_text"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `type: "reasoning"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The type of the object. Always `reasoning`. + - `"in_progress"` - - `"reasoning"` + - `"completed"` - - `agent: optional object { agent_name }` + - `"incomplete"` - The agent that produced this item. + - `MultiAgentCall object { id, action, arguments, 3 more }` - - `agent_name: string` + - `id: string` - The canonical name of the agent that produced this item. + The unique ID of the multi-agent call item. - - `content: optional array of object { text, type }` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - Reasoning text content. + The multi-agent action to execute. - - `text: string` + - `"spawn_agent"` - The reasoning text from the model. + - `"interrupt_agent"` - - `type: "reasoning_text"` + - `"list_agents"` - The type of the reasoning text. Always `reasoning_text`. + - `"send_message"` - - `"reasoning_text"` + - `"followup_task"` - - `encrypted_content: optional string` + - `"wait_agent"` - 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. + - `arguments: string` - - `status: optional "in_progress" or "completed" or "incomplete"` + The JSON string of arguments generated for the action. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `call_id: string` - - `"in_progress"` + The unique ID linking this call to its output. - - `"completed"` + - `type: "multi_agent_call"` - - `"incomplete"` + The type of the multi-agent call. Always `multi_agent_call`. - - `Program object { id, call_id, code, 3 more }` + - `"multi_agent_call"` - - `id: string` + - `agent: optional object { agent_name }` - The unique ID of the program item. + The agent that produced this item. - - `call_id: string` + - `agent_name: string` - The stable call ID of the program item. + The canonical name of the agent that produced this item. - - `code: string` + - `MultiAgentCallOutput object { id, action, call_id, 3 more }` - The JavaScript source executed by programmatic tool calling. + - `id: string` - - `fingerprint: string` + The unique ID of the multi-agent call output item. - Opaque program replay fingerprint that must be round-tripped. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `type: "program"` + The multi-agent action that produced this result. - The type of the item. Always `program`. + - `"spawn_agent"` - - `"program"` + - `"interrupt_agent"` - - `agent: optional object { agent_name }` + - `"list_agents"` - The agent that produced this item. + - `"send_message"` - - `agent_name: string` + - `"followup_task"` - The canonical name of the agent that produced this item. + - `"wait_agent"` - - `ProgramOutput object { id, call_id, result, 3 more }` + - `call_id: string` - - `id: string` + The unique ID of the multi-agent call. - The unique ID of the program output item. + - `output: array of BetaResponseOutputText` - - `call_id: string` + Text output returned by the multi-agent action. - The call ID of the program item. + - `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 }` - - `result: string` + The annotations of the text output. - The result produced by the program item. + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - - `status: "completed" or "incomplete"` + - `text: string` - The terminal status of the program output item. + The text output from the model. - - `"completed"` + - `type: "output_text"` - - `"incomplete"` + The type of the output text. Always `output_text`. - - `type: "program_output"` + - `type: "multi_agent_call_output"` - The type of the item. Always `program_output`. + The type of the multi-agent result. Always `multi_agent_call_output`. - - `"program_output"` + - `"multi_agent_call_output"` - `agent: optional object { agent_name }` @@ -25005,8 +25640,40 @@ Retrieves a model response with the given ID. - `BetaContainerNetworkPolicyDisabled object { type }` + - `type: "disabled"` + + Disable outbound network access. Always `disabled`. + + - `"disabled"` + - `BetaContainerNetworkPolicyAllowlist 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 BetaContainerNetworkPolicyDomainSecret` + + 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`. @@ -25187,11 +25854,129 @@ Retrieves a model response with the given ID. - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `BetaLocalEnvironment object { type, skills }` + - `type: "container_auto"` - - `BetaContainerReference object { container_id, type }` + Automatically creates a container for this request - - `Custom object { name, type, allowed_callers, 3 more }` + - `"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 BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `BetaContainerNetworkPolicyDisabled object { type }` + + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `skills: optional array of BetaSkillReference or BetaInlineSkill` + + An optional list of skills referenced by id or inline data. + + - `BetaSkillReference 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. + + - `BetaInlineSkill object { description, name, source, type }` + + - `description: string` + + The description of the skill. + + - `name: string` + + The name of the skill. + + - `source: BetaInlineSkillSource` + + 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"` + + - `BetaLocalEnvironment object { type, skills }` + + - `type: "local"` + + Use a local computer environment. + + - `"local"` + + - `skills: optional array of BetaLocalSkill` + + 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. + + - `BetaContainerReference 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) @@ -26526,23 +27311,141 @@ Retrieves a model response with the given ID. The canonical name of the agent that produced this item. - - `Compaction object { id, encrypted_content, type, 2 more }` - - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + - `AgentMessage object { id, author, content, 3 more }` - `id: string` - The unique ID of the compaction item. + The unique ID of the agent message. + + - `author: string` + + The sending agent identity. + + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + + Encrypted content sent between agents. + + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `BetaResponseOutputText object { annotations, logprobs, text, type }` + + A text output from the model. + + - `Text object { text, type }` + + A text content. + + - `text: string` + + - `type: "text"` + + - `"text"` + + - `SummaryText object { text, type }` + + A summary text from the model. + + - `text: string` + + A summary of the reasoning output from the model so far. + + - `type: "summary_text"` + + The type of the object. Always `summary_text`. + + - `"summary_text"` + + - `ReasoningText object { text, type }` + + Reasoning text from the model. + + - `text: string` + + The reasoning text from the model. + + - `type: "reasoning_text"` + + The type of the reasoning text. Always `reasoning_text`. + + - `"reasoning_text"` + + - `BetaResponseOutputRefusal object { refusal, type }` + + A refusal from the model. + + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](/docs/guides/vision). + + - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` + + A screenshot of a computer. + + - `detail: "low" or "high" or "auto" or "original"` + + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `file_id: string` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: string` + + The URL of the screenshot image. + + - `type: "computer_screenshot"` + + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + + - `"computer_screenshot"` + + - `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"` + + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `EncryptedContent object { encrypted_content, type }` + + Opaque encrypted content that Responses API decrypts inside trusted model execution. - `encrypted_content: string` - The encrypted content that was produced by compaction. + Opaque encrypted content. - - `type: "compaction"` + - `type: "encrypted_content"` - The type of the item. Always `compaction`. + The type of the input item. Always `encrypted_content`. - - `"compaction"` + - `"encrypted_content"` + + - `recipient: string` + + The destination agent identity. + + - `type: "agent_message"` + + The type of the item. Always `agent_message`. + + - `"agent_message"` - `agent: optional object { agent_name }` @@ -26552,9 +27455,272 @@ Retrieves a model response with the given ID. The canonical name of the agent that produced this item. - - `created_by: optional string` + - `FunctionCallOutput object { call_id, output, type, 4 more }` - The identifier of the actor that created the item. + The output of a function tool call. + + - `call_id: string` + + The unique ID of the function tool call generated by the model. + + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + + The output from the function call generated by your code. + Can be a string or an list of output content. + + - `StringOutput = string` + + A string of the output of the function call. + + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + + Text, image, or file output of the function call. + + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](/docs/guides/vision). + + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `type: "function_call_output"` + + The type of the function tool call output. Always `function_call_output`. + + - `"function_call_output"` + + - `id: optional string` + + The unique ID of the function tool call output. Populated when this item + is returned via API. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `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"` + + - `FileSearchCall object { id, queries, status, 3 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"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `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. + + - `WebSearchCall object { id, action, status, 2 more }` + + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. + + - `id: string` + + The unique ID of the web search tool call. + + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). + + - `Search object { type, queries, query, sources }` + + Action type "search" - Performs a web search query. + + - `type: "search"` + + The action type. + + - `"search"` + + - `queries: optional array of string` + + The search queries. + + - `query: optional string` + + The search query. + + - `sources: optional array of object { type, url }` + + The sources used in the search. + + - `type: "url"` + + The type of source. Always `url`. + + - `"url"` + + - `url: string` + + The URL of the source. + + - `OpenPage object { type, url }` + + Action type "open_page" - Opens a specific URL from search results. + + - `type: "open_page"` + + The action type. + + - `"open_page"` + + - `url: optional string` + + The URL opened by the model. + + - `FindInPage object { pattern, type, url }` + + Action type "find_in_page": Searches for a pattern within a loaded page. + + - `pattern: string` + + The pattern or text to search for within the page. + + - `type: "find_in_page"` + + The action type. + + - `"find_in_page"` + + - `url: string` + + The URL of the page searched for the pattern. + + - `status: "in_progress" or "searching" or "completed" or "failed"` + + The status of the web search tool call. + + - `"in_progress"` + + - `"searching"` + + - `"completed"` + + - `"failed"` + + - `type: "web_search_call"` + + The type of the web search tool call. Always `web_search_call`. + + - `"web_search_call"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. - `ImageGenerationCall object { id, result, status, 2 more }` @@ -26594,6 +27760,473 @@ Retrieves a model response with the given ID. The canonical name of the agent that produced this item. + - `ComputerCall object { id, call_id, pending_safety_checks, 5 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 BetaComputerAction` + + A click action. + + - `Click object { button, type, x, 2 more }` + + A click action. + + - `button: "left" or "right" or "wheel" or 2 more` + + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + + - `"left"` + + - `"right"` + + - `"wheel"` + + - `"back"` + + - `"forward"` + + - `type: "click"` + + Specifies the event type. For a click action, this property is always `click`. + + - `"click"` + + - `x: number` + + The x-coordinate where the click occurred. + + - `y: number` + + The y-coordinate where the click occurred. + + - `keys: optional array of string` + + The keys being held while clicking. + + - `DoubleClick object { keys, type, x, y }` + + A double click action. + + - `keys: array of string` + + The keys being held while double-clicking. + + - `type: "double_click"` + + Specifies the event type. For a double click action, this property is always set to `double_click`. + + - `"double_click"` + + - `x: number` + + The x-coordinate where the double click occurred. + + - `y: number` + + The y-coordinate where the double click occurred. + + - `Drag object { path, type, keys }` + + A drag action. + + - `path: array of object { x, y }` + + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` + + - `x: number` + + The x-coordinate. + + - `y: number` + + The y-coordinate. + + - `type: "drag"` + + Specifies the event type. For a drag action, this property is always set to `drag`. + + - `"drag"` + + - `keys: optional array of string` + + The keys being held while dragging the mouse. + + - `Keypress object { keys, type }` + + A collection of keypresses the model would like to perform. + + - `keys: array of string` + + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + + - `type: "keypress"` + + Specifies the event type. For a keypress action, this property is always set to `keypress`. + + - `"keypress"` + + - `Move object { type, x, y, keys }` + + A mouse move action. + + - `type: "move"` + + Specifies the event type. For a move action, this property is always set to `move`. + + - `"move"` + + - `x: number` + + The x-coordinate to move to. + + - `y: number` + + The y-coordinate to move to. + + - `keys: optional array of string` + + The keys being held while moving the mouse. + + - `Screenshot object { type }` + + A screenshot action. + + - `type: "screenshot"` + + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + + - `"screenshot"` + + - `Scroll object { scroll_x, scroll_y, type, 3 more }` + + A scroll action. + + - `scroll_x: number` + + The horizontal scroll distance. + + - `scroll_y: number` + + The vertical scroll distance. + + - `type: "scroll"` + + Specifies the event type. For a scroll action, this property is always set to `scroll`. + + - `"scroll"` + + - `x: number` + + The x-coordinate where the scroll occurred. + + - `y: number` + + The y-coordinate where the scroll occurred. + + - `keys: optional array of string` + + The keys being held while scrolling. + + - `Type object { text, type }` + + An action to type in text. + + - `text: string` + + The text to type. + + - `type: "type"` + + Specifies the event type. For a type action, this property is always set to `type`. + + - `"type"` + + - `Wait object { type }` + + A wait action. + + - `type: "wait"` + + Specifies the event type. For a wait action, this property is always set to `wait`. + + - `"wait"` + + - `actions: optional BetaComputerActionList` + + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. + + - `Click object { button, type, x, 2 more }` + + A click action. + + - `DoubleClick object { keys, type, x, y }` + + A double click action. + + - `Drag object { path, type, keys }` + + A drag action. + + - `Keypress object { keys, type }` + + A collection of keypresses the model would like to perform. + + - `Move object { type, x, y, keys }` + + A mouse move action. + + - `Screenshot object { type }` + + A screenshot action. + + - `Scroll object { scroll_x, scroll_y, type, 3 more }` + + A scroll action. + + - `Type object { text, type }` + + An action to type in text. + + - `Wait object { type }` + + A wait action. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `ComputerCallOutput object { id, call_id, output, 5 more }` + + - `id: string` + + The unique ID of the computer call tool output. + + - `call_id: string` + + The ID of the computer tool call that produced the output. + + - `output: BetaResponseComputerToolCallOutputScreenshot` + + A computer screenshot image used with the computer use tool. + + - `type: "computer_screenshot"` + + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. + + - `"computer_screenshot"` + + - `file_id: optional string` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: optional string` + + The URL of the screenshot image. + + - `status: "completed" or "incomplete" or "failed" or "in_progress"` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `"completed"` + + - `"incomplete"` + + - `"failed"` + + - `"in_progress"` + + - `type: "computer_call_output"` + + The type of the computer tool call output. Always `computer_call_output`. + + - `"computer_call_output"` + + - `acknowledged_safety_checks: optional array of object { id, code, message }` + + The safety checks reported by the API that have been acknowledged by the + developer. + + - `id: string` + + The ID of the pending safety check. + + - `code: optional string` + + The type of the pending safety check. + + - `message: optional string` + + Details about the pending safety check. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `Reasoning object { id, summary, type, 4 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 object { text, type }` + + 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"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `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 { id, encrypted_content, type, 2 more }` + + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + + - `id: string` + + The unique ID of the compaction item. + + - `encrypted_content: string` + + The encrypted content that was produced by compaction. + + - `type: "compaction"` + + The type of the item. Always `compaction`. + + - `"compaction"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `created_by: optional string` + + The identifier of the actor that created the item. + - `CodeInterpreterCall object { id, code, container_id, 4 more }` A tool call to run code. @@ -27155,67 +28788,6 @@ Retrieves a model response with the given ID. Optional textual output returned by the apply patch tool. - - `McpCall object { id, arguments, name, 7 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"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `approval_request_id: optional string` - - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - - `error: optional string` - - The error from the tool call, if any. - - - `output: optional string` - - The output from the tool call. - - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `"calling"` - - - `"failed"` - - `McpListTools object { id, server_label, tools, 3 more }` A list of tools available on an MCP server. @@ -27334,6 +28906,67 @@ Retrieves a model response with the given ID. Optional reason for the decision. + - `McpCall object { id, arguments, name, 7 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"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `approval_request_id: optional string` + + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + + - `error: optional string` + + The error from the tool call, if any. + + - `output: optional string` + + The output from the tool call. + + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"calling"` + + - `"failed"` + - `CustomToolCall object { call_id, input, name, 5 more }` A call to a custom tool created by the model. @@ -27392,11 +29025,9 @@ Retrieves a model response with the given ID. The namespace of the custom tool being called. - - `CustomToolCallOutput object { id, call_id, output, 5 more }` - - - `id: string` + - `CustomToolCallOutput object { call_id, output, type, 3 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` @@ -27427,23 +29058,16 @@ Retrieves a model response with the given ID. 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. + - `agent: optional object { agent_name }` The agent that produced this item. @@ -27476,3145 +29100,2925 @@ Retrieves a model response with the given ID. - `"program"` - - `created_by: optional string` + - `usage: BetaResponseUsage` - The identifier of the actor that created the item. + Token accounting for the compaction pass, including cached, reasoning, and total tokens. - - `parallel_tool_calls: boolean` + - `input_tokens: number` - Whether to allow the model to run tool calls in parallel. + The number of input tokens. - - `temperature: number` + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` - 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. + A detailed breakdown of the input tokens. - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + - `cache_write_tokens: number` - 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 number of input tokens that were written to the cache. - - `BetaToolChoiceOptions = "none" or "auto" or "required"` + - `cached_tokens: number` - Controls which (if any) tool is called by the model. + The number of tokens that were retrieved from the cache. + [More on prompt caching](/docs/guides/prompt-caching). - `none` means the model will not call any tool and instead generates a message. + - `output_tokens: number` - `auto` means the model can pick between generating a message or calling one or - more tools. + The number of output tokens. - `required` means the model must call one or more tools. + - `output_tokens_details: object { reasoning_tokens }` - - `"none"` + A detailed breakdown of the output tokens. - - `"auto"` + - `reasoning_tokens: number` - - `"required"` + The number of reasoning tokens. - - `BetaToolChoiceAllowed object { mode, tools, type }` + - `total_tokens: number` - Constrains the tools available to the model to a pre-defined set. + The total number of tokens used. - - `mode: "auto" or "required"` +### Example - Constrains the tools available to the model to a pre-defined set. +```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" + }' +``` - `auto` allows the model to pick from among the allowed tools and generate a - message. +#### Response - `required` requires the model to call one or more of the allowed tools. +```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", + "agent": { + "agent_name": "agent_name" + }, + "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 + } +} +``` - - `"auto"` +### Example - - `"required"` +```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" + } + ] + }' +``` - - `tools: array of map[unknown]` +#### Response - A list of tool definitions that the model should be allowed to call. +```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 + } +} +``` - For the Responses API, the list of tool definitions might look like: +## Create a model response - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` +**post** `/responses?beta=true` - - `type: "allowed_tools"` +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. - Allowed tool configuration type. Always `allowed_tools`. +### Header Parameters - - `"allowed_tools"` +- `"openai-beta": optional array of "responses_multi_agent=v1"` - - `BetaToolChoiceTypes object { type }` + - `"responses_multi_agent=v1"` - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](/docs/guides/tools). +### Body Parameters - - `type: "file_search" or "web_search_preview" or "computer" or 5 more` +- `background: optional boolean` - The type of hosted tool the model should to use. Learn more about - [built-in tools](/docs/guides/tools). + Whether to run the model response in the background. + [Learn more](/docs/guides/background). - Allowed values are: +- `context_management: optional array of object { type, compact_threshold }` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + Context management configuration for this request. - - `"file_search"` + - `type: string` - - `"web_search_preview"` + The context management entry type. Currently only 'compaction' is supported. - - `"computer"` + - `compact_threshold: optional number` - - `"computer_use_preview"` + Token threshold at which compaction should be triggered for this entry. - - `"computer_use"` +- `conversation: optional string or BetaResponseConversationParam` - - `"web_search_preview_2025_03_11"` + 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. - - `"image_generation"` + - `ConversationID = string` - - `"code_interpreter"` + The unique ID of the conversation. - - `BetaToolChoiceFunction object { name, type }` + - `BetaResponseConversationParam object { id }` - Use this option to force the model to call a specific function. + The conversation that this response belongs to. - - `name: string` + - `id: string` - The name of the function to call. + The unique ID of the conversation. - - `type: "function"` +- `include: optional array of BetaResponseIncludable` - For function calling, the type is always `function`. + Specify additional output data to include in the model response. Currently supported values are: - - `"function"` + - `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). - - `BetaToolChoiceMcp object { server_label, type, name }` + - `"file_search_call.results"` - Use this option to force the model to call a specific tool on a remote MCP server. + - `"web_search_call.results"` - - `server_label: string` + - `"web_search_call.action.sources"` - The label of the MCP server to use. + - `"message.input_image.image_url"` - - `type: "mcp"` + - `"computer_call_output.output.image_url"` - For MCP tools, the type is always `mcp`. + - `"code_interpreter_call.outputs"` - - `"mcp"` + - `"reasoning.encrypted_content"` - - `name: optional string` + - `"message.output_text.logprobs"` - The name of the tool to call on the server. +- `input: optional string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - - `BetaToolChoiceCustom object { name, type }` + Text, image, or file inputs to the model, used to generate a response. - Use this option to force the model to call a specific custom tool. + Learn more: - - `name: string` + - [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) - The name of the custom tool to call. + - `TextInput = string` - - `type: "custom"` + A text input to the model, equivalent to a text input with the + `user` role. - For custom tool calling, the type is always `custom`. + - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - - `"custom"` + A list of one or many input items to the model, containing + different content types. - - `BetaSpecificProgrammaticToolCallingParam object { type }` + - `BetaEasyInputMessage object { content, role, phase, type }` - - `type: "programmatic_tool_calling"` + 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 tool to call. Always `programmatic_tool_calling`. + - `content: string or BetaResponseInputMessageContentList` - - `"programmatic_tool_calling"` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `BetaToolChoiceApplyPatch object { type }` + - `TextInput = string` - Forces the model to call the apply_patch tool when executing a tool call. + A text input to the model. - - `type: "apply_patch"` + - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` - The tool to call. Always `apply_patch`. + A list of one or many input items to the model, containing different content + types. - - `"apply_patch"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `BetaToolChoiceShell object { type }` + A text input to the model. - Forces the model to call the shell tool when a tool call is required. + - `text: string` - - `type: "shell"` + The text input to the model. - The tool to call. Always `shell`. + - `type: "input_text"` - - `"shell"` + The type of the input item. Always `input_text`. - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + - `"input_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. + - `prompt_cache_breakpoint: optional object { mode }` - We support the following categories of tools: + 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. - - **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. + - `mode: "explicit"` - - `Function object { name, parameters, strict, 5 more }` + The breakpoint mode. Always `explicit`. - 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). + - `"explicit"` - - `name: string` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - The name of the function to call. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `parameters: map[unknown]` + - `detail: "low" or "high" or "auto" or "original"` - A JSON schema object describing the parameters of the function. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `strict: boolean` + - `"low"` - Whether strict parameter validation is enforced for this function tool. + - `"high"` - - `type: "function"` + - `"auto"` - The type of the function tool. Always `function`. + - `"original"` - - `"function"` + - `type: "input_image"` - - `allowed_callers: optional array of "direct" or "programmatic"` + The type of the input item. Always `input_image`. - The tool invocation context(s). + - `"input_image"` - - `"direct"` + - `file_id: optional string` - - `"programmatic"` + The ID of the file to be sent to the model. - - `defer_loading: optional boolean` + - `image_url: optional string` - Whether this function is deferred and loaded 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. - - `description: optional string` + - `prompt_cache_breakpoint: optional object { mode }` - A description of the function. Used by the model to determine whether or not to call the function. + 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. - - `output_schema: optional map[unknown]` + - `mode: "explicit"` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The breakpoint mode. Always `explicit`. - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `"explicit"` - 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). + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `type: "file_search"` + A file input to the model. - The type of the file search tool. Always `file_search`. + - `type: "input_file"` - - `"file_search"` + The type of the input item. Always `input_file`. - - `vector_store_ids: array of string` + - `"input_file"` - The IDs of the vector stores to search. + - `detail: optional "auto" or "low" or "high"` - - `filters: optional object { key, type, value } or object { filters, 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`. - A filter to apply. + - `"auto"` - - `ComparisonFilter object { key, type, value }` + - `"low"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"high"` - - `key: string` + - `file_data: optional string` - The key to compare against the value. + The content of the file to be sent to the model. - - `type: "eq" or "ne" or "gt" or 5 more` + - `file_id: optional string` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The ID of the file to be sent to the model. - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `file_url: optional string` - - `"eq"` + The URL of the file to be sent to the model. - - `"ne"` + - `filename: optional string` - - `"gt"` + The name of the file to be sent to the model. - - `"gte"` + - `prompt_cache_breakpoint: optional object { mode }` - - `"lt"` + 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. - - `"lte"` + - `mode: "explicit"` - - `"in"` + The breakpoint mode. Always `explicit`. - - `"nin"` + - `"explicit"` - - `value: string or number or boolean or array of string or number` + - `role: "user" or "assistant" or "system" or "developer"` - The value to compare against the attribute key; supports string, number, or boolean types. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `string` + - `"user"` - - `number` + - `"assistant"` - - `boolean` + - `"system"` - - `array of string or number` + - `"developer"` - - `string` + - `phase: optional "commentary" or "final_answer"` - - `number` + 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. - - `CompoundFilter object { filters, type }` + - `"commentary"` - Combine multiple filters using `and` or `or`. + - `"final_answer"` - - `filters: array of object { key, type, value } or unknown` + - `type: optional "message"` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + The type of the message input. Always `message`. - - `ComparisonFilter object { key, type, value }` + - `"message"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `Message object { content, role, agent, 2 more }` - - `key: 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. - The key to compare against the value. + - `content: BetaResponseInputMessageContentList` - - `type: "eq" or "ne" or "gt" or 5 more` + A list of one or many input items to the model, containing different content + types. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `role: "user" or "system" or "developer"` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + The role of the message input. One of `user`, `system`, or `developer`. - - `"eq"` + - `"user"` - - `"ne"` + - `"system"` - - `"gt"` + - `"developer"` - - `"gte"` + - `agent: optional object { agent_name }` - - `"lt"` + The agent that produced this item. - - `"lte"` + - `agent_name: string` - - `"in"` + The canonical name of the agent that produced this item. - - `"nin"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `value: string or number or boolean or array of string or number` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The value to compare against the attribute key; supports string, number, or boolean types. + - `"in_progress"` - - `string` + - `"completed"` - - `number` + - `"incomplete"` - - `boolean` + - `type: optional "message"` - - `array of string or number` + The type of the message input. Always set to `message`. - - `string` + - `"message"` - - `number` + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - - `unknown` + An output message from the model. - - `type: "and" or "or"` + - `id: string` - Type of operation: `and` or `or`. + The unique ID of the output message. - - `"and"` + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - - `"or"` + The content of the output message. - - `max_num_results: optional number` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + A text output from the model. - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `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 }` - Ranking options for search. + The annotations of the text output. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `FileCitation object { file_id, filename, index, type }` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + A citation to a file. - - `embedding_weight: number` + - `file_id: string` - The weight of the embedding in the reciprocal ranking fusion. + The ID of the file. - - `text_weight: number` + - `filename: string` - The weight of the text in the reciprocal ranking fusion. + The filename of the file cited. - - `ranker: optional "auto" or "default-2024-11-15"` + - `index: number` - The ranker to use for the file search. + The index of the file in the list of files. - - `"auto"` + - `type: "file_citation"` - - `"default-2024-11-15"` + The type of the file citation. Always `file_citation`. - - `score_threshold: optional number` + - `"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. + - `URLCitation object { end_index, start_index, title, 2 more }` - - `Computer object { type }` + A citation for a web resource used to generate a model response. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `end_index: number` - - `type: "computer"` + The index of the last character of the URL citation in the message. - The type of the computer tool. Always `computer`. + - `start_index: number` - - `"computer"` + The index of the first character of the URL citation in the message. - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `title: string` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The title of the web resource. - - `display_height: number` + - `type: "url_citation"` - The height of the computer display. + The type of the URL citation. Always `url_citation`. - - `display_width: number` + - `"url_citation"` - The width of the computer display. + - `url: string` - - `environment: "windows" or "mac" or "linux" or 2 more` + The URL of the web resource. - The type of computer environment to control. + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - - `"windows"` + A citation for a container file used to generate a model response. - - `"mac"` + - `container_id: string` - - `"linux"` + The ID of the container file. - - `"ubuntu"` + - `end_index: number` - - `"browser"` + The index of the last character of the container file citation in the message. - - `type: "computer_use_preview"` + - `file_id: string` - The type of the computer use tool. Always `computer_use_preview`. + The ID of the file. - - `"computer_use_preview"` + - `filename: string` - - `WebSearch object { type, filters, search_context_size, user_location }` + The filename of the container file cited. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + - `start_index: number` - - `type: "web_search" or "web_search_2025_08_26"` + The index of the first character of the container file citation in the message. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `type: "container_file_citation"` - - `"web_search"` + The type of the container file citation. Always `container_file_citation`. - - `"web_search_2025_08_26"` + - `"container_file_citation"` - - `filters: optional object { allowed_domains }` + - `FilePath object { file_id, index, type }` - Filters for the search. + A path to a file. - - `allowed_domains: optional array of string` + - `file_id: string` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + The ID of the file. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `index: number` - - `search_context_size: optional "low" or "medium" or "high"` + The index of the file in the list of files. - 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: "file_path"` - - `"low"` + The type of the file path. Always `file_path`. - - `"medium"` + - `"file_path"` - - `"high"` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - - `user_location: optional object { city, country, region, 2 more }` + - `token: string` - The approximate location of the user. + - `bytes: array of number` - - `city: optional string` + - `logprob: number` - Free text input for the city of the user, e.g. `San Francisco`. + - `top_logprobs: array of object { token, bytes, logprob }` - - `country: optional string` + - `token: string` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `bytes: array of number` - - `region: optional string` + - `logprob: number` - Free text input for the region of the user, e.g. `California`. + - `text: string` - - `timezone: optional string` + The text output from the model. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `type: "output_text"` - - `type: optional "approximate"` + The type of the output text. Always `output_text`. - The type of location approximation. Always `approximate`. + - `"output_text"` - - `"approximate"` + - `BetaResponseOutputRefusal object { refusal, type }` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + A refusal from 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). + - `refusal: string` - - `server_label: string` + The refusal explanation from the model. - A label for this MCP server, used to identify it in tool calls. + - `type: "refusal"` - - `type: "mcp"` + The type of the refusal. Always `refusal`. - The type of the MCP tool. Always `mcp`. + - `"refusal"` - - `"mcp"` + - `role: "assistant"` - - `allowed_callers: optional array of "direct" or "programmatic"` + The role of the output message. Always `assistant`. - The tool invocation context(s). + - `"assistant"` - - `"direct"` + - `status: "in_progress" or "completed" or "incomplete"` - - `"programmatic"` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `"in_progress"` - List of allowed tool names or a filter object. + - `"completed"` - - `McpAllowedTools = array of string` + - `"incomplete"` - A string array of allowed tool names + - `type: "message"` - - `McpToolFilter object { read_only, tool_names }` + The type of the output message. Always `message`. - A filter object to specify which tools are allowed. + - `"message"` - - `read_only: optional boolean` + - `agent: optional object { agent_name }` - 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 agent that produced this item. - - `tool_names: optional array of string` + - `agent_name: string` - List of allowed tool names. + The canonical name of the agent that produced this item. - - `authorization: optional string` + - `phase: optional "commentary" or "final_answer"` - 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. + 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. - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `"commentary"` - 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). + - `"final_answer"` - Currently supported `connector_id` values are: + - `FileSearchCall object { id, queries, status, 3 more }` - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - - `"connector_dropbox"` + - `id: string` - - `"connector_gmail"` + The unique ID of the file search tool call. - - `"connector_googlecalendar"` + - `queries: array of string` - - `"connector_googledrive"` + The queries used to search for files. - - `"connector_microsoftteams"` + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `"connector_outlookcalendar"` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `"connector_outlookemail"` + - `"in_progress"` - - `"connector_sharepoint"` + - `"searching"` - - `defer_loading: optional boolean` + - `"completed"` - Whether this MCP tool is deferred and discovered via tool search. + - `"incomplete"` - - `headers: optional map[string]` + - `"failed"` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `type: "file_search_call"` - - `require_approval: optional object { always, never } or "always" or "never"` + The type of the file search tool call. Always `file_search_call`. - Specify which of the MCP server's tools require approval. + - `"file_search_call"` - - `McpToolApprovalFilter object { always, never }` + - `agent: optional object { agent_name }` - 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 agent that produced this item. - - `always: optional object { read_only, tool_names }` + - `agent_name: string` - A filter object to specify which tools are allowed. + The canonical name of the agent that produced this item. - - `read_only: optional boolean` + - `results: optional array of object { attributes, file_id, filename, 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. + The results of the file search tool call. - - `tool_names: optional array of string` + - `attributes: optional map[string or number or boolean]` - List 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. - - `never: optional 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` - - `McpToolApprovalSetting = "always" or "never"` + The name of the 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. + - `score: optional number` - - `"always"` + The relevance score of the file - a value between 0 and 1. - - `"never"` + - `text: optional string` - - `server_description: optional string` + The text that was retrieved from the file. - Optional description of the MCP server, used to provide more context. + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - - `server_url: optional string` + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `id: string` - - `tunnel_id: optional string` + The unique ID of the 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. + - `call_id: string` - - `CodeInterpreter object { container, type, allowed_callers }` + An identifier used when responding to the tool call with output. - A tool that runs Python code to help generate a response to a prompt. + - `pending_safety_checks: array of object { id, code, message }` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + The pending safety checks for the computer call. - 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. + - `id: string` - - `string` + The ID of the pending safety check. - The container ID. + - `code: optional string` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + The type of the pending safety check. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `message: optional string` - - `type: "auto"` + Details about the pending safety check. - Always `auto`. + - `status: "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. - - `file_ids: optional array of string` + - `"in_progress"` - An optional list of uploaded files to make available to your code. + - `"completed"` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `"incomplete"` - The memory limit for the code interpreter container. + - `type: "computer_call"` - - `"1g"` + The type of the computer call. Always `computer_call`. - - `"4g"` + - `"computer_call"` - - `"16g"` + - `action: optional BetaComputerAction` - - `"64g"` + A click action. - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `Click object { button, type, x, 2 more }` - Network access policy for the container. + A click action. - - `BetaContainerNetworkPolicyDisabled object { type }` + - `button: "left" or "right" or "wheel" or 2 more` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `type: "code_interpreter"` + - `"left"` - The type of the code interpreter tool. Always `code_interpreter`. + - `"right"` - - `"code_interpreter"` + - `"wheel"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"back"` - The tool invocation context(s). + - `"forward"` - - `"direct"` + - `type: "click"` - - `"programmatic"` + Specifies the event type. For a click action, this property is always `click`. - - `ProgrammaticToolCalling object { type }` + - `"click"` - - `type: "programmatic_tool_calling"` + - `x: number` - The type of the tool. Always `programmatic_tool_calling`. + The x-coordinate where the click occurred. - - `"programmatic_tool_calling"` + - `y: number` - - `ImageGeneration object { type, action, background, 9 more }` + The y-coordinate where the click occurred. - A tool that generates images using the GPT image models. + - `keys: optional array of string` - - `type: "image_generation"` + The keys being held while clicking. - The type of the image generation tool. Always `image_generation`. + - `DoubleClick object { keys, type, x, y }` - - `"image_generation"` + A double click action. - - `action: optional "generate" or "edit" or "auto"` + - `keys: array of string` - Whether to generate a new image or edit an existing image. Default: `auto`. + The keys being held while double-clicking. - - `"generate"` + - `type: "double_click"` - - `"edit"` + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `"auto"` + - `"double_click"` - - `background: optional "transparent" or "opaque" or "auto"` + - `x: number` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + The x-coordinate where the double click occurred. - - `"transparent"` + - `y: number` - - `"opaque"` + The y-coordinate where the double click occurred. - - `"auto"` + - `Drag object { path, type, keys }` - - `input_fidelity: optional "high" or "low"` + A drag action. - 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`. + - `path: array of object { x, y }` - - `"high"` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `"low"` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `input_image_mask: optional object { file_id, image_url }` + - `x: number` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + The x-coordinate. - - `file_id: optional string` + - `y: number` - File ID for the mask image. + The y-coordinate. - - `image_url: optional string` + - `type: "drag"` - Base64-encoded mask image. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"drag"` - The image generation model to use. Default: `gpt-image-1`. + - `keys: optional array of string` - - `string` + The keys being held while dragging the mouse. - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `Keypress object { keys, type }` - The image generation model to use. Default: `gpt-image-1`. + A collection of keypresses the model would like to perform. - - `"gpt-image-1"` + - `keys: array of string` - - `"gpt-image-1-mini"` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `"gpt-image-1.5"` + - `type: "keypress"` - - `moderation: optional "auto" or "low"` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - Moderation level for the generated image. Default: `auto`. + - `"keypress"` - - `"auto"` + - `Move object { type, x, y, keys }` - - `"low"` + A mouse move action. - - `output_compression: optional number` + - `type: "move"` - Compression level for the output image. Default: 100. + Specifies the event type. For a move action, this property is always set to `move`. - - `output_format: optional "png" or "webp" or "jpeg"` + - `"move"` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `x: number` - - `"png"` + The x-coordinate to move to. - - `"webp"` + - `y: number` - - `"jpeg"` + The y-coordinate to move to. - - `partial_images: optional number` + - `keys: optional array of string` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The keys being held while moving the mouse. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `Screenshot object { type }` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + A screenshot action. - - `"low"` + - `type: "screenshot"` - - `"medium"` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `"high"` + - `"screenshot"` - - `"auto"` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + A scroll 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`. + - `scroll_x: number` - - `string` + The horizontal scroll distance. - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `scroll_y: number` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + The vertical scroll distance. - - `"1024x1024"` + - `type: "scroll"` - - `"1024x1536"` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `"1536x1024"` + - `"scroll"` - - `"auto"` + - `x: number` - - `LocalShell object { type }` + The x-coordinate where the scroll occurred. - A tool that allows the model to execute shell commands in a local environment. + - `y: number` - - `type: "local_shell"` + The y-coordinate where the scroll occurred. - The type of the local shell tool. Always `local_shell`. + - `keys: optional array of string` - - `"local_shell"` + The keys being held while scrolling. - - `Shell object { type, allowed_callers, environment }` + - `Type object { text, type }` - A tool that allows the model to execute shell commands. + An action to type in text. - - `type: "shell"` + - `text: string` - The type of the shell tool. Always `shell`. + The text to type. - - `"shell"` + - `type: "type"` - - `allowed_callers: optional array of "direct" or "programmatic"` + Specifies the event type. For a type action, this property is always set to `type`. - The tool invocation context(s). + - `"type"` - - `"direct"` + - `Wait object { type }` - - `"programmatic"` + A wait action. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `type: "wait"` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + Specifies the event type. For a wait action, this property is always set to `wait`. - - `BetaLocalEnvironment object { type, skills }` + - `"wait"` - - `BetaContainerReference object { container_id, type }` + - `actions: optional BetaComputerActionList` - - `Custom object { name, type, allowed_callers, 3 more }` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `Click object { button, type, x, 2 more }` - - `name: string` + A click action. - The name of the custom tool, used to identify it in tool calls. + - `DoubleClick object { keys, type, x, y }` - - `type: "custom"` + A double click action. - The type of the custom tool. Always `custom`. + - `Drag object { path, type, keys }` - - `"custom"` + A drag action. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `Keypress object { keys, type }` - The tool invocation context(s). + A collection of keypresses the model would like to perform. - - `"direct"` + - `Move object { type, x, y, keys }` - - `"programmatic"` + A mouse move action. - - `defer_loading: optional boolean` + - `Screenshot object { type }` - Whether this tool should be deferred and discovered via tool search. + A screenshot action. - - `description: optional string` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - Optional description of the custom tool, used to provide more context. + A scroll action. - - `format: optional object { type } or object { definition, syntax, type }` + - `Type object { text, type }` - The input format for the custom tool. Default is unconstrained text. + An action to type in text. - - `Text object { type }` + - `Wait object { type }` - Unconstrained free-form text. + A wait action. - - `type: "text"` + - `agent: optional object { agent_name }` - Unconstrained text format. Always `text`. + The agent that produced this item. - - `"text"` + - `agent_name: string` - - `Grammar object { definition, syntax, type }` + The canonical name of the agent that produced this item. - A grammar defined by the user. + - `ComputerCallOutput object { call_id, output, type, 4 more }` - - `definition: string` + The output of a computer tool call. - The grammar definition. + - `call_id: string` - - `syntax: "lark" or "regex"` + The ID of the computer tool call that produced the output. - The syntax of the grammar definition. One of `lark` or `regex`. + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `"lark"` + A computer screenshot image used with the computer use tool. - - `"regex"` + - `type: "computer_screenshot"` - - `type: "grammar"` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - Grammar format. Always `grammar`. + - `"computer_screenshot"` - - `"grammar"` + - `file_id: optional string` - - `Namespace object { description, name, tools, type }` + The identifier of an uploaded file that contains the screenshot. - Groups function/custom tools under a shared namespace. + - `image_url: optional string` - - `description: string` + The URL of the screenshot image. - A description of the namespace shown to the model. + - `type: "computer_call_output"` - - `name: string` + The type of the computer tool call output. Always `computer_call_output`. - The namespace name used in tool calls (for example, `crm`). + - `"computer_call_output"` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `id: optional string` - The function/custom tools available inside this namespace. + The ID of the computer tool call output. - - `Function object { name, type, allowed_callers, 5 more }` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `name: string` + The safety checks reported by the API that have been acknowledged by the developer. - - `type: "function"` + - `id: string` - - `"function"` + 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` + - `agent: optional object { agent_name }` - Whether this function should be deferred and discovered via tool search. + The agent that produced this item. - - `description: optional string` + - `agent_name: string` - - `output_schema: optional map[unknown]` + The canonical name of the agent that produced this item. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `parameters: optional unknown` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - `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) + - `WebSearchCall object { id, action, status, 2 more }` - - `name: string` + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - The name of the custom tool, used to identify it in tool calls. + - `id: string` - - `type: "custom"` + The unique ID of the web search tool call. - The type of the custom tool. Always `custom`. + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `"custom"` + 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). - - `allowed_callers: optional array of "direct" or "programmatic"` + - `Search object { type, queries, query, sources }` - The tool invocation context(s). + Action type "search" - Performs a web search query. - - `"direct"` + - `type: "search"` - - `"programmatic"` + The action type. - - `defer_loading: optional boolean` + - `"search"` - Whether this tool should be deferred and discovered via tool search. + - `queries: optional array of string` - - `description: optional string` + The search queries. - Optional description of the custom tool, used to provide more context. + - `query: optional string` - - `format: optional object { type } or object { definition, syntax, type }` + The search query. - The input format for the custom tool. Default is unconstrained text. + - `sources: optional array of object { type, url }` - - `Text object { type }` + The sources used in the search. - Unconstrained free-form text. + - `type: "url"` - - `type: "text"` + The type of source. Always `url`. - Unconstrained text format. Always `text`. + - `"url"` - - `"text"` + - `url: string` - - `Grammar object { definition, syntax, type }` + The URL of the source. - A grammar defined by the user. + - `OpenPage object { type, url }` - - `definition: string` + Action type "open_page" - Opens a specific URL from search results. - The grammar definition. + - `type: "open_page"` - - `syntax: "lark" or "regex"` + The action type. - The syntax of the grammar definition. One of `lark` or `regex`. + - `"open_page"` - - `"lark"` + - `url: optional string` - - `"regex"` + The URL opened by the model. - - `type: "grammar"` + - `FindInPage object { pattern, type, url }` - Grammar format. Always `grammar`. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `"grammar"` + - `pattern: string` - - `type: "namespace"` + The pattern or text to search for within the page. - The type of the tool. Always `namespace`. + - `type: "find_in_page"` - - `"namespace"` + The action type. - - `ToolSearch object { type, description, execution, parameters }` + - `"find_in_page"` - Hosted or BYOT tool search configuration for deferred tools. + - `url: string` - - `type: "tool_search"` + The URL of the page searched for the pattern. - The type of the tool. Always `tool_search`. + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `"tool_search"` + The status of the web search tool call. - - `description: optional string` + - `"in_progress"` - Description shown to the model for a client-executed tool search tool. + - `"searching"` - - `execution: optional "server" or "client"` + - `"completed"` - Whether tool search is executed by the server or by the client. + - `"failed"` - - `"server"` + - `type: "web_search_call"` - - `"client"` + The type of the web search tool call. Always `web_search_call`. - - `parameters: optional unknown` + - `"web_search_call"` - Parameter schema for a client-executed tool search tool. + - `agent: optional object { agent_name }` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + The agent that produced this item. - 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). + - `agent_name: string` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + The canonical name of the agent that produced this item. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `FunctionCall object { arguments, call_id, name, 6 more }` - - `"web_search_preview"` + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `"web_search_preview_2025_03_11"` + - `arguments: string` - - `search_content_types: optional array of "text" or "image"` + A JSON string of the arguments to pass to the function. - - `"text"` + - `call_id: string` - - `"image"` + The unique ID of the function 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 function to run. - - `"low"` + - `type: "function_call"` - - `"medium"` + The type of the function tool call. Always `function_call`. - - `"high"` + - `"function_call"` - - `user_location: optional object { type, city, country, 2 more }` + - `id: optional string` - The user's location. + The unique ID of the function tool call. - - `type: "approximate"` + - `agent: optional object { agent_name }` - The type of location approximation. Always `approximate`. + The agent that produced this item. - - `"approximate"` + - `agent_name: string` - - `city: optional string` + The canonical name of the agent that produced this item. - Free text input for the city of the user, e.g. `San Francisco`. + - `caller: optional object { type } or object { caller_id, type }` - - `country: optional string` + The execution context that produced this tool call. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `Direct object { type }` - - `region: optional string` + - `type: "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"` + - `"program"` - The type of the tool. Always `apply_patch`. + - `namespace: optional string` - - `"apply_patch"` + The namespace of the function to run. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `status: optional "in_progress" or "completed" or "incomplete"` - The tool invocation context(s). + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"direct"` + - `"in_progress"` - - `"programmatic"` + - `"completed"` - - `top_p: number` + - `"incomplete"` - 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. + - `FunctionCallOutput object { call_id, output, type, 4 more }` - We generally recommend altering this or `temperature` but not both. + The output of a function tool call. - - `background: optional boolean` + - `call_id: string` - Whether to run the model response in the background. - [Learn more](/docs/guides/background). + The unique ID of the function tool call generated by the model. - - `completed_at: optional number` + - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + Text, image, or file output of the function tool call. - - `conversation: optional object { id }` + - `string` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + A JSON string of the output of the function tool call. - - `id: string` + - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - The unique ID of the conversation that this response was associated with. + An array of content outputs (text, image, file) for the function tool call. - - `max_output_tokens: optional number` + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - 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). + A text input to the model. - - `max_tool_calls: optional number` + - `text: string` - 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 text input to the model. - - `moderation: optional object { input, output }` + - `type: "input_text"` - Moderation results for the response input and output, if moderated completions were requested. + The type of the input item. Always `input_text`. - - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + - `"input_text"` - Moderation for the response input. + - `prompt_cache_breakpoint: optional object { mode }` - - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 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. - A moderation result produced for the response input or output. + - `mode: "explicit"` - - `categories: map[boolean]` + The breakpoint mode. Always `explicit`. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `"explicit"` - - `category_applied_input_types: map[array of "text" or "image"]` + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - Which modalities of input are reflected by the score for each category. + An image input to the model. Learn about [image inputs](/docs/guides/vision) - - `"text"` + - `type: "input_image"` - - `"image"` + The type of the input item. Always `input_image`. - - `category_scores: map[number]` + - `"input_image"` - A dictionary of moderation categories to scores. + - `detail: optional "low" or "high" or "auto" or "original"` - - `flagged: boolean` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - A boolean indicating whether the content was flagged by any category. + - `"low"` - - `model: string` + - `"high"` - The moderation model that produced this result. + - `"auto"` - - `type: "moderation_result"` + - `"original"` - The object type, which was always `moderation_result` for successful moderation results. + - `file_id: optional string` - - `"moderation_result"` + The ID of the file to be sent to the model. - - `Error object { code, message, type }` + - `image_url: optional string` - An error produced while attempting moderation for the response input or output. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `code: string` + - `prompt_cache_breakpoint: optional object { mode }` - The error code. + 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. - - `message: string` + - `mode: "explicit"` - The error message. + The breakpoint mode. Always `explicit`. - - `type: "error"` + - `"explicit"` - The object type, which was always `error` for moderation failures. + - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` - - `"error"` + A file input to the model. - - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + - `type: "input_file"` - Moderation for the response output. + The type of the input item. Always `input_file`. - - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + - `"input_file"` - A moderation result produced for the response input or output. + - `detail: optional "auto" or "low" or "high"` - - `categories: map[boolean]` + 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`. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `"auto"` - - `category_applied_input_types: map[array of "text" or "image"]` + - `"low"` - Which modalities of input are reflected by the score for each category. + - `"high"` - - `"text"` + - `file_data: optional string` - - `"image"` + The base64-encoded data of the file to be sent to the model. - - `category_scores: map[number]` + - `file_id: optional string` - A dictionary of moderation categories to scores. + The ID of the file to be sent to the model. - - `flagged: boolean` + - `file_url: optional string` - A boolean indicating whether the content was flagged by any category. + The URL of the file to be sent to the model. - - `model: string` + - `filename: optional string` - The moderation model that produced this result. + The name of the file to be sent to the model. - - `type: "moderation_result"` + - `prompt_cache_breakpoint: optional object { mode }` - The object type, which was always `moderation_result` for successful moderation results. + 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. - - `"moderation_result"` + - `mode: "explicit"` - - `Error object { code, message, type }` + The breakpoint mode. Always `explicit`. - An error produced while attempting moderation for the response input or output. + - `"explicit"` - - `code: string` + - `type: "function_call_output"` - The error code. + The type of the function tool call output. Always `function_call_output`. - - `message: string` + - `"function_call_output"` - The error message. + - `id: optional string` - - `type: "error"` + The unique ID of the function tool call output. Populated when this item is returned via API. - The object type, which was always `error` for moderation failures. + - `agent: optional object { agent_name }` - - `"error"` + The agent that produced this item. - - `output_text: optional string` + - `agent_name: 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. + The canonical name of the agent that produced this item. - - `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 BetaResponsePrompt` + - `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` + The caller type. Always `direct`. - The unique identifier of the prompt template to use. + - `"direct"` - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + - `Program object { caller_id, type }` - 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. + - `caller_id: string` - - `string` + The call ID of the program item that produced this tool call. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `type: "program"` - A text input to the model. + The caller type. Always `program`. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `"program"` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `status: optional "in_progress" or "completed" or "incomplete"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - A file input to the model. + - `"in_progress"` - - `version: optional string` + - `"completed"` - Optional version of the prompt template. + - `"incomplete"` - - `prompt_cache_key: optional string` + - `AgentMessage object { author, content, recipient, 3 more }` - 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). + A message routed between agents. - - `prompt_cache_options: optional object { mode, ttl }` + - `author: string` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + The sending agent identity. - - `mode: "implicit" or "explicit"` + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - Whether implicit prompt-cache breakpoints were enabled. + Plaintext, image, or encrypted content sent between agents. - - `"implicit"` + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - - `"explicit"` + A text input to the model. - - `ttl: "30m"` + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - The minimum lifetime applied to each cache breakpoint. + An image input to the model. Learn about [image inputs](/docs/guides/vision) - - `"30m"` + - `EncryptedContent object { encrypted_content, type }` - - `prompt_cache_retention: optional "in_memory" or "24h"` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - Deprecated. Use `prompt_cache_options.ttl` instead. + - `encrypted_content: string` - 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. + Opaque encrypted content. - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `type: "encrypted_content"` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + The type of the input item. Always `encrypted_content`. - - `"in_memory"` + - `"encrypted_content"` - - `"24h"` + - `recipient: string` - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + The destination agent identity. - **gpt-5 and o-series models only** + - `type: "agent_message"` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + The item type. Always `agent_message`. - - `context: optional "auto" or "current_turn" or "all_turns"` + - `"agent_message"` - 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`. + - `id: optional string` - When returned on a response, this is the effective reasoning context mode - used for the response. + The unique ID of this agent message item. - - `"auto"` + - `agent: optional object { agent_name }` - - `"current_turn"` + The agent that produced this item. - - `"all_turns"` + - `agent_name: string` - - `effort: optional "none" or "minimal" or "low" or 4 more` + The canonical name of the agent that produced this item. - 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. + - `MultiAgentCall object { action, arguments, call_id, 3 more }` - - `"none"` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `"minimal"` + The multi-agent action that was executed. - - `"low"` + - `"spawn_agent"` - - `"medium"` + - `"interrupt_agent"` - - `"high"` + - `"list_agents"` - - `"xhigh"` + - `"send_message"` - - `"max"` + - `"followup_task"` - - `generate_summary: optional "auto" or "concise" or "detailed"` + - `"wait_agent"` - **Deprecated:** use `summary` instead. + - `arguments: 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 action arguments as a JSON string. - - `"auto"` + - `call_id: string` - - `"concise"` + The unique ID linking this call to its output. - - `"detailed"` + - `type: "multi_agent_call"` - - `mode: optional string or "standard" or "pro"` + The item type. Always `multi_agent_call`. - Controls the reasoning execution mode for the request. + - `"multi_agent_call"` - When returned on a response, this is the effective execution mode. + - `id: optional string` - - `string` + The unique ID of this multi-agent call. - - `"standard" or "pro"` + - `agent: optional object { agent_name }` - Controls the reasoning execution mode for the request. + The agent that produced this item. - When returned on a response, this is the effective execution mode. + - `agent_name: string` - - `"standard"` + The canonical name of the agent that produced this item. - - `"pro"` + - `MultiAgentCallOutput object { action, call_id, output, 3 more }` - - `summary: optional "auto" or "concise" or "detailed"` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - 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 multi-agent action that produced this result. - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `"spawn_agent"` - - `"auto"` + - `"interrupt_agent"` - - `"concise"` + - `"list_agents"` - - `"detailed"` + - `"send_message"` - - `safety_identifier: optional string` + - `"followup_task"` - 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). + - `"wait_agent"` - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + - `call_id: string` - Specifies the processing type used for serving the request. + The unique ID of the multi-agent 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'. + - `output: array of object { text, type, annotations }` - 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. + Text output returned by the multi-agent action. - - `"auto"` + - `text: string` - - `"default"` + The text content. - - `"flex"` + - `type: "output_text"` - - `"scale"` + The content type. Always `output_text`. - - `"priority"` + - `"output_text"` - - `status: optional BetaResponseStatus` + - `annotations: optional 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 }` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + Citations associated with the text content. - - `"completed"` + - `FileCitation object { file_id, filename, index, type }` - - `"failed"` + - `file_id: string` - - `"in_progress"` + The ID of the file. - - `"cancelled"` + - `filename: string` - - `"queued"` + The filename of the file cited. - - `"incomplete"` + - `index: number` - - `text: optional BetaResponseTextConfig` + The index of the file in the list of files. - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `type: "file_citation"` - - [Text inputs and outputs](/docs/guides/text) - - [Structured Outputs](/docs/guides/structured-outputs) + The citation type. Always `file_citation`. - - `format: optional BetaResponseFormatTextConfig` + - `"file_citation"` - An object specifying the format that the model must output. + - `URLCitation object { end_index, start_index, title, 2 more }` - 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). + - `end_index: number` - The default format is `{ "type": "text" }` with no additional options. + The index of the last character of the citation in the message. - **Not recommended for gpt-4o and newer models:** + - `start_index: number` - 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 index of the first character of the citation in the message. - - `Text object { type }` + - `title: string` - Default response format. Used to generate text responses. + The title of the cited resource. - - `type: "text"` + - `type: "url_citation"` - The type of response format being defined. Always `text`. + The citation type. Always `url_citation`. - - `"text"` + - `"url_citation"` - - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` + - `url: string` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + The URL of the cited resource. - - `name: string` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - 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. + - `container_id: string` - - `schema: map[unknown]` + The ID of the container. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `end_index: number` - - `type: "json_schema"` + The index of the last character of the citation in the message. - The type of response format being defined. Always `json_schema`. + - `file_id: string` - - `"json_schema"` + The ID of the container file. - - `description: optional string` + - `filename: string` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The filename of the container file cited. - - `strict: optional boolean` + - `start_index: number` - 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 index of the first character of the citation in the message. - - `JSONObject object { type }` + - `type: "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. + The citation type. Always `container_file_citation`. - - `type: "json_object"` + - `"container_file_citation"` - The type of response format being defined. Always `json_object`. + - `type: "multi_agent_call_output"` - - `"json_object"` + The item type. Always `multi_agent_call_output`. - - `verbosity: optional "low" or "medium" or "high"` + - `"multi_agent_call_output"` - 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`. + - `id: optional string` - - `"low"` + The unique ID of this multi-agent call output. - - `"medium"` + - `agent: optional object { agent_name }` - - `"high"` + The agent that produced this item. - - `top_logprobs: optional number` + - `agent_name: string` - 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. + The canonical name of the agent that produced this item. - - `truncation: optional "auto" or "disabled"` + - `ToolSearchCall object { arguments, type, id, 4 more }` - The truncation strategy to use for the model response. + - `arguments: unknown` - - `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 arguments supplied to the tool search call. - - `"auto"` + - `type: "tool_search_call"` - - `"disabled"` + The item type. Always `tool_search_call`. - - `usage: optional BetaResponseUsage` + - `"tool_search_call"` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `id: optional string` - - `input_tokens: number` + The unique ID of this tool search call. - The number of input tokens. + - `agent: optional object { agent_name }` - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + The agent that produced this item. - A detailed breakdown of the input tokens. + - `agent_name: string` - - `cache_write_tokens: number` + The canonical name of the agent that produced this item. - The number of input tokens that were written to the cache. + - `call_id: optional string` - - `cached_tokens: number` + The unique ID of the tool search call generated by the model. - The number of tokens that were retrieved from the cache. - [More on prompt caching](/docs/guides/prompt-caching). + - `execution: optional "server" or "client"` - - `output_tokens: number` + Whether tool search was executed by the server or by the client. - The number of output tokens. + - `"server"` - - `output_tokens_details: object { reasoning_tokens }` + - `"client"` - A detailed breakdown of the output tokens. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `reasoning_tokens: number` + The status of the tool search call. - The number of reasoning tokens. + - `"in_progress"` - - `total_tokens: number` + - `"completed"` - The total number of tokens used. + - `"incomplete"` - - `user: optional string` + - `ToolSearchOutput object { tools, type, id, 4 more }` - 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). + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` -### Example + The loaded tool definitions returned by the tool search output. -```http -curl https://api.openai.com/v1/responses/$RESPONSE_ID \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `Function object { name, parameters, strict, 5 more }` -#### Response + 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). -```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", - "agent": { - "agent_name": "agent_name" - }, - "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" -} -``` + - `name: string` -### Example + The name of the function to call. -```http -curl https://api.openai.com/v1/responses/resp_123 \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `parameters: map[unknown]` -#### Response + A JSON schema object describing the parameters of the function. -```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": {} -} -``` + - `strict: boolean` -## Delete a model response + Whether strict parameter validation is enforced for this function tool. -**delete** `/responses/{response_id}?beta=true` + - `type: "function"` -Deletes a model response with the given ID. + The type of the function tool. Always `function`. -### Path Parameters + - `"function"` -- `response_id: string` + - `allowed_callers: optional array of "direct" or "programmatic"` -### Header Parameters + The tool invocation context(s). -- `"openai-beta": optional array of "responses_multi_agent=v1"` + - `"direct"` - - `"responses_multi_agent=v1"` + - `"programmatic"` -### Example + - `defer_loading: optional boolean` -```http -curl https://api.openai.com/v1/responses/$RESPONSE_ID \ - -X DELETE \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + Whether this function is deferred and loaded via tool search. -### Example + - `description: optional string` -```http -curl -X DELETE https://api.openai.com/v1/responses/resp_123 \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + A description of the function. Used by the model to determine whether or not to call the function. -#### Response + - `output_schema: optional map[unknown]` -```json -{ - "id": "resp_6786a1bec27481909a17d673315b29f6", - "object": "response", - "deleted": true -} -``` + A JSON schema object describing the JSON value encoded in string outputs for this function. -## Cancel a response + - `FileSearch object { type, vector_store_ids, filters, 2 more }` -**post** `/responses/{response_id}/cancel?beta=true` + 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). -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). + - `type: "file_search"` -### Path Parameters + The type of the file search tool. Always `file_search`. -- `response_id: string` + - `"file_search"` -### Header Parameters + - `vector_store_ids: array of string` -- `"openai-beta": optional array of "responses_multi_agent=v1"` + The IDs of the vector stores to search. - - `"responses_multi_agent=v1"` + - `filters: optional object { key, type, value } or object { filters, type }` -### Returns + A filter to apply. -- `BetaResponse object { id, created_at, error, 32 more }` + - `ComparisonFilter object { key, type, value }` - - `id: string` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - Unique identifier for this Response. + - `key: string` - - `created_at: number` + The key to compare against the value. - Unix timestamp (in seconds) of when this Response was created. + - `type: "eq" or "ne" or "gt" or 5 more` - - `error: BetaResponseError` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - An error object returned when the model fails to generate a Response. + - `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 - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 17 more` + - `"eq"` - The error code for the response. + - `"ne"` - - `"server_error"` + - `"gt"` - - `"rate_limit_exceeded"` + - `"gte"` - - `"invalid_prompt"` + - `"lt"` - - `"data_residency_mismatch"` + - `"lte"` - - `"bio_policy"` + - `"in"` - - `"vector_store_timeout"` + - `"nin"` - - `"invalid_image"` + - `value: string or number or boolean or array of string or number` - - `"invalid_image_format"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `"invalid_base64_image"` + - `string` - - `"invalid_image_url"` + - `number` - - `"image_too_large"` + - `boolean` - - `"image_too_small"` + - `array of string or number` - - `"image_parse_error"` + - `string` - - `"image_content_policy_violation"` + - `number` - - `"invalid_image_mode"` + - `CompoundFilter object { filters, type }` - - `"image_file_too_large"` + Combine multiple filters using `and` or `or`. - - `"unsupported_image_media_type"` + - `filters: array of object { key, type, value } or unknown` - - `"empty_image_file"` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `"failed_to_download_image"` + - `ComparisonFilter object { key, type, value }` - - `"image_file_not_found"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `message: string` + - `key: string` - A human-readable description of the error. + The key to compare against the value. - - `incomplete_details: object { reason }` + - `type: "eq" or "ne" or "gt" or 5 more` - Details about why the response is incomplete. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `reason: optional "max_output_tokens" or "content_filter"` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - The reason why the response is incomplete. + - `"eq"` - - `"max_output_tokens"` + - `"ne"` - - `"content_filter"` + - `"gt"` - - `instructions: string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + - `"gte"` - A system (or developer) message inserted into the model's context. + - `"lt"` - 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. + - `"lte"` - - `string` + - `"in"` - A text input to the model, equivalent to a text input with the - `developer` role. + - `"nin"` - - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + - `value: string or number or boolean or array of string or number` - A list of one or many input items to the model, containing - different content types. + The value to compare against the attribute key; supports string, number, or boolean types. - - `BetaEasyInputMessage object { content, role, phase, type }` + - `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. + - `number` - - `content: string or BetaResponseInputMessageContentList` + - `boolean` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `array of string or number` - - `TextInput = string` + - `string` - A text input to the model. + - `number` - - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` + - `unknown` - A list of one or many input items to the model, containing different content - types. + - `type: "and" or "or"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + Type of operation: `and` or `or`. - A text input to the model. + - `"and"` - - `text: string` + - `"or"` - The text input to the model. + - `max_num_results: optional number` - - `type: "input_text"` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - The type of the input item. Always `input_text`. + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `"input_text"` + Ranking options for search. - - `prompt_cache_breakpoint: optional object { mode }` + - `hybrid_search: optional object { embedding_weight, text_weight }` - 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. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `mode: "explicit"` + - `embedding_weight: number` - The breakpoint mode. Always `explicit`. + The weight of the embedding in the reciprocal ranking fusion. - - `"explicit"` + - `text_weight: number` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + The weight of the text in the reciprocal ranking fusion. - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `ranker: optional "auto" or "default-2024-11-15"` - - `detail: "low" or "high" or "auto" or "original"` + The ranker to use for the file search. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"auto"` - - `"low"` + - `"default-2024-11-15"` - - `"high"` + - `score_threshold: optional number` - - `"auto"` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - - `"original"` + - `Computer object { type }` - - `type: "input_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 input item. Always `input_image`. + - `type: "computer"` - - `"input_image"` + The type of the computer tool. Always `computer`. - - `file_id: optional string` + - `"computer"` - The ID of the file to be sent to the model. + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `image_url: optional string` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `display_height: number` - - `prompt_cache_breakpoint: optional object { mode }` + The height of the computer display. - 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. + - `display_width: number` - - `mode: "explicit"` + The width of the computer display. - The breakpoint mode. Always `explicit`. + - `environment: "windows" or "mac" or "linux" or 2 more` - - `"explicit"` + The type of computer environment to control. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `"windows"` - A file input to the model. + - `"mac"` - - `type: "input_file"` + - `"linux"` - The type of the input item. Always `input_file`. + - `"ubuntu"` - - `"input_file"` + - `"browser"` - - `detail: optional "auto" or "low" or "high"` + - `type: "computer_use_preview"` - 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 computer use tool. Always `computer_use_preview`. - - `"auto"` + - `"computer_use_preview"` - - `"low"` + - `WebSearch object { type, filters, search_context_size, user_location }` - - `"high"` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `file_data: optional string` + - `type: "web_search" or "web_search_2025_08_26"` - The content of the file to be sent to the model. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `file_id: optional string` + - `"web_search"` - The ID of the file to be sent to the model. + - `"web_search_2025_08_26"` - - `file_url: optional string` + - `filters: optional object { allowed_domains }` - The URL of the file to be sent to the model. + Filters for the search. - - `filename: optional string` + - `allowed_domains: optional array of string` - The name of the file to be sent to the model. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `prompt_cache_breakpoint: optional object { mode }` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - 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_context_size: optional "low" or "medium" or "high"` - - `mode: "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. - The breakpoint mode. Always `explicit`. + - `"low"` - - `"explicit"` + - `"medium"` - - `role: "user" or "assistant" or "system" or "developer"` + - `"high"` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + - `user_location: optional object { city, country, region, 2 more }` - - `"user"` + The approximate location of the user. - - `"assistant"` + - `city: optional string` - - `"system"` + Free text input for the city of the user, e.g. `San Francisco`. - - `"developer"` + - `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` - - `type: optional "message"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The type of the message input. Always `message`. + - `type: optional "approximate"` - - `"message"` + The type of location approximation. Always `approximate`. - - `Message object { content, role, agent, 2 more }` + - `"approximate"` - 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. + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `content: BetaResponseInputMessageContentList` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - A list of one or many input items to the model, containing different content - types. + - `server_label: string` - - `role: "user" or "system" or "developer"` + A label for this MCP server, used to identify it in tool calls. - The role of the message input. One of `user`, `system`, or `developer`. + - `type: "mcp"` - - `"user"` + The type of the MCP tool. Always `mcp`. - - `"system"` + - `"mcp"` - - `"developer"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `agent: optional object { agent_name }` + The tool invocation context(s). - The agent that produced this item. + - `"direct"` - - `agent_name: string` + - `"programmatic"` - The canonical name of the agent that produced this item. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `status: optional "in_progress" or "completed" or "incomplete"` + List of allowed tool names or a filter object. - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `McpAllowedTools = array of string` - - `"in_progress"` + A string array of allowed tool names - - `"completed"` + - `McpToolFilter object { read_only, tool_names }` - - `"incomplete"` + A filter object to specify which tools are allowed. - - `type: optional "message"` + - `read_only: optional boolean` - The type of the message input. Always set to `message`. + 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"` + - `tool_names: optional array of string` - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + List of allowed tool names. - An output message from the model. + - `authorization: optional string` - - `id: string` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - The unique ID of the output message. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + 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 content of the output message. + Currently supported `connector_id` values are: - - `BetaResponseOutputText object { annotations, logprobs, text, type }` + - 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 text output from the model. + - `"connector_dropbox"` - - `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 }` + - `"connector_gmail"` - The annotations of the text output. + - `"connector_googlecalendar"` - - `FileCitation object { file_id, filename, index, type }` + - `"connector_googledrive"` - A citation to a file. + - `"connector_microsoftteams"` - - `file_id: string` + - `"connector_outlookcalendar"` - The ID of the file. + - `"connector_outlookemail"` - - `filename: string` + - `"connector_sharepoint"` - The filename of the file cited. + - `defer_loading: optional boolean` - - `index: number` + Whether this MCP tool is deferred and discovered via tool search. - The index of the file in the list of files. + - `headers: optional map[string]` - - `type: "file_citation"` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The type of the file citation. Always `file_citation`. + - `require_approval: optional object { always, never } or "always" or "never"` - - `"file_citation"` + Specify which of the MCP server's tools require approval. - - `URLCitation object { end_index, start_index, title, 2 more }` + - `McpToolApprovalFilter object { always, never }` - A citation for a web resource used to generate a model response. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `end_index: number` + - `always: optional object { read_only, tool_names }` - The index of the last character of the URL citation in the message. + A filter object to specify which tools are allowed. - - `start_index: number` + - `read_only: optional boolean` - The index of the first character of the URL citation in the message. + 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. - - `title: string` + - `tool_names: optional array of string` - The title of the web resource. + List of allowed tool names. - - `type: "url_citation"` + - `never: optional object { read_only, tool_names }` - The type of the URL citation. Always `url_citation`. + A filter object to specify which tools are allowed. - - `"url_citation"` + - `read_only: optional boolean` - - `url: 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 URL of the web resource. + - `tool_names: optional array of string` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + List of allowed tool names. - A citation for a container file used to generate a model response. + - `McpToolApprovalSetting = "always" or "never"` - - `container_id: 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. - The ID of the container file. + - `"always"` - - `end_index: number` + - `"never"` - The index of the last character of the container file citation in the message. + - `server_description: optional string` - - `file_id: string` + Optional description of the MCP server, used to provide more context. - The ID of the file. + - `server_url: optional string` - - `filename: string` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - The filename of the container file cited. + - `tunnel_id: optional string` - - `start_index: number` + 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 index of the first character of the container file citation in the message. + - `CodeInterpreter object { container, type, allowed_callers }` - - `type: "container_file_citation"` + A tool that runs Python code to help generate a response to a prompt. - The type of the container file citation. Always `container_file_citation`. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `"container_file_citation"` + 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. - - `FilePath object { file_id, index, type }` + - `string` - A path to a file. + 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. - - `index: number` + - `type: "auto"` - The index of the file in the list of files. + Always `auto`. - - `type: "file_path"` + - `"auto"` - The type of the file path. Always `file_path`. + - `file_ids: optional array of string` - - `"file_path"` + An optional list of uploaded files to make available to your code. - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `token: string` + The memory limit for the code interpreter container. - - `bytes: array of number` + - `"1g"` - - `logprob: number` + - `"4g"` - - `top_logprobs: array of object { token, bytes, logprob }` + - `"16g"` - - `token: string` + - `"64g"` - - `bytes: array of number` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `logprob: number` + Network access policy for the container. - - `text: string` + - `BetaContainerNetworkPolicyDisabled object { type }` - The text output from the model. + - `type: "disabled"` - - `type: "output_text"` + Disable outbound network access. Always `disabled`. - The type of the output text. Always `output_text`. + - `"disabled"` - - `"output_text"` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `BetaResponseOutputRefusal object { refusal, type }` + - `allowed_domains: array of string` - A refusal from the model. + A list of allowed domains when type is `allowlist`. - - `refusal: string` + - `type: "allowlist"` - The refusal explanation from the model. + Allow outbound network access only to specified domains. Always `allowlist`. - - `type: "refusal"` + - `"allowlist"` - The type of the refusal. Always `refusal`. + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - - `"refusal"` + Optional domain-scoped secrets for allowlisted domains. - - `role: "assistant"` + - `domain: string` - The role of the output message. Always `assistant`. + The domain associated with the secret. - - `"assistant"` + - `name: string` - - `status: "in_progress" or "completed" or "incomplete"` + The name of the secret to inject for the domain. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `value: string` - - `"in_progress"` + The secret value to inject for the domain. - - `"completed"` + - `type: "code_interpreter"` - - `"incomplete"` + The type of the code interpreter tool. Always `code_interpreter`. - - `type: "message"` + - `"code_interpreter"` - The type of the output message. Always `message`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"message"` + The tool invocation context(s). - - `agent: optional object { agent_name }` + - `"direct"` - The agent that produced this item. + - `"programmatic"` - - `agent_name: string` + - `ProgrammaticToolCalling object { type }` - The canonical name of the agent that produced this item. + - `type: "programmatic_tool_calling"` - - `phase: optional "commentary" or "final_answer"` + The type of the tool. Always `programmatic_tool_calling`. - 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_tool_calling"` - - `"commentary"` + - `ImageGeneration object { type, action, background, 9 more }` - - `"final_answer"` + A tool that generates images using the GPT image models. - - `FileSearchCall object { id, queries, status, 3 more }` + - `type: "image_generation"` - The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + The type of the image generation tool. Always `image_generation`. - - `id: string` + - `"image_generation"` - The unique ID of the file search tool call. + - `action: optional "generate" or "edit" or "auto"` - - `queries: array of string` + Whether to generate a new image or edit an existing image. Default: `auto`. - The queries used to search for files. + - `"generate"` - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `"edit"` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `"auto"` - - `"in_progress"` + - `background: optional "transparent" or "opaque" or "auto"` - - `"searching"` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `"completed"` + - `"transparent"` - - `"incomplete"` + - `"opaque"` - - `"failed"` + - `"auto"` - - `type: "file_search_call"` + - `input_fidelity: optional "high" or "low"` - The type of the file search tool call. Always `file_search_call`. + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `"file_search_call"` + - `"high"` - - `agent: optional object { agent_name }` + - `"low"` - The agent that produced this item. + - `input_image_mask: optional object { file_id, image_url }` - - `agent_name: string` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - The canonical name of the agent that produced this item. + - `file_id: optional string` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + File ID for the mask image. - The results of the file search tool call. + - `image_url: optional string` - - `attributes: optional map[string or number or boolean]` + Base64-encoded mask image. - 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. + - `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` - - `number` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `boolean` + The image generation model to use. Default: `gpt-image-1`. - - `file_id: optional string` + - `"gpt-image-1"` - The unique ID of the file. + - `"gpt-image-1-mini"` - - `filename: optional string` + - `"gpt-image-1.5"` - The name of the file. + - `moderation: optional "auto" or "low"` - - `score: optional number` + Moderation level for the generated image. Default: `auto`. - The relevance score of the file - a value between 0 and 1. + - `"auto"` - - `text: optional string` + - `"low"` - The text that was retrieved from the file. + - `output_compression: optional number` - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + Compression level for the output image. Default: 100. - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + - `output_format: optional "png" or "webp" or "jpeg"` - - `id: string` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The unique ID of the computer call. + - `"png"` - - `call_id: string` + - `"webp"` - An identifier used when responding to the tool call with output. + - `"jpeg"` - - `pending_safety_checks: array of object { id, code, message }` + - `partial_images: optional number` - The pending safety checks for the computer call. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `id: string` + - `quality: optional "low" or "medium" or "high" or "auto"` - The ID of the pending safety check. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `code: optional string` + - `"low"` - The type of the pending safety check. + - `"medium"` - - `message: optional string` + - `"high"` - Details about the pending safety check. + - `"auto"` - - `status: "in_progress" or "completed" or "incomplete"` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + 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`. - - `"in_progress"` + - `string` - - `"completed"` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `"incomplete"` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `type: "computer_call"` + - `"1024x1024"` - The type of the computer call. Always `computer_call`. + - `"1024x1536"` - - `"computer_call"` + - `"1536x1024"` - - `action: optional BetaComputerAction` + - `"auto"` - A click action. + - `LocalShell object { type }` - - `Click object { button, type, x, 2 more }` + A tool that allows the model to execute shell commands in a local environment. - A click action. + - `type: "local_shell"` - - `button: "left" or "right" or "wheel" or 2 more` + The type of the local shell tool. Always `local_shell`. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `"local_shell"` - - `"left"` + - `Shell object { type, allowed_callers, environment }` - - `"right"` + A tool that allows the model to execute shell commands. - - `"wheel"` + - `type: "shell"` - - `"back"` + The type of the shell tool. Always `shell`. - - `"forward"` + - `"shell"` - - `type: "click"` + - `allowed_callers: optional array of "direct" or "programmatic"` - Specifies the event type. For a click action, this property is always `click`. + The tool invocation context(s). - - `"click"` + - `"direct"` - - `x: number` + - `"programmatic"` - The x-coordinate where the click occurred. + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `y: number` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - The y-coordinate where the click occurred. + - `type: "container_auto"` - - `keys: optional array of string` + Automatically creates a container for this request - The keys being held while clicking. + - `"container_auto"` - - `DoubleClick object { keys, type, x, y }` + - `file_ids: optional array of string` - A double click action. + An optional list of uploaded files to make available to your code. - - `keys: array of string` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The keys being held while double-clicking. + The memory limit for the container. - - `type: "double_click"` + - `"1g"` - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `"4g"` - - `"double_click"` + - `"16g"` - - `x: number` + - `"64g"` - The x-coordinate where the double click occurred. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `y: number` + Network access policy for the container. - The y-coordinate where the double click occurred. + - `BetaContainerNetworkPolicyDisabled object { type }` - - `Drag object { path, type, keys }` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - A drag action. + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - - `path: array of object { x, y }` + An optional list of skills referenced by id or inline data. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `BetaSkillReference object { skill_id, type, version }` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `skill_id: string` - - `x: number` + The ID of the referenced skill. - The x-coordinate. + - `type: "skill_reference"` - - `y: number` + References a skill created with the /v1/skills endpoint. - The y-coordinate. + - `"skill_reference"` - - `type: "drag"` + - `version: optional string` - Specifies the event type. For a drag action, this property is always set to `drag`. + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `"drag"` + - `BetaInlineSkill object { description, name, source, type }` - - `keys: optional array of string` + - `description: string` - The keys being held while dragging the mouse. + The description of the skill. - - `Keypress object { keys, type }` + - `name: string` - A collection of keypresses the model would like to perform. + The name of the skill. - - `keys: array of string` + - `source: BetaInlineSkillSource` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + Inline skill payload - - `type: "keypress"` + - `data: string` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + Base64-encoded skill zip bundle. - - `"keypress"` + - `media_type: "application/zip"` - - `Move object { type, x, y, keys }` + The media type of the inline skill payload. Must be `application/zip`. - A mouse move action. + - `"application/zip"` - - `type: "move"` + - `type: "base64"` - Specifies the event type. For a move action, this property is always set to `move`. + The type of the inline skill source. Must be `base64`. - - `"move"` + - `"base64"` - - `x: number` + - `type: "inline"` - The x-coordinate to move to. + Defines an inline skill for this request. - - `y: number` + - `"inline"` - The y-coordinate to move to. + - `BetaLocalEnvironment object { type, skills }` - - `keys: optional array of string` + - `type: "local"` - The keys being held while moving the mouse. + Use a local computer environment. - - `Screenshot object { type }` + - `"local"` - A screenshot action. + - `skills: optional array of BetaLocalSkill` - - `type: "screenshot"` + An optional list of skills. - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `description: string` - - `"screenshot"` + The description of the skill. - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `name: string` - A scroll action. + The name of the skill. - - `scroll_x: number` + - `path: string` - The horizontal scroll distance. + The path to the directory containing the skill. - - `scroll_y: number` + - `BetaContainerReference object { container_id, type }` - The vertical scroll distance. + - `container_id: string` - - `type: "scroll"` + The ID of the referenced container. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `type: "container_reference"` - - `"scroll"` + References a container created with the /v1/containers endpoint - - `x: number` + - `"container_reference"` - The x-coordinate where the scroll occurred. + - `Custom object { name, type, allowed_callers, 3 more }` - - `y: number` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - The y-coordinate where the scroll occurred. + - `name: string` - - `keys: optional array of string` + The name of the custom tool, used to identify it in tool calls. - The keys being held while scrolling. + - `type: "custom"` - - `Type object { text, type }` + The type of the custom tool. Always `custom`. - An action to type in text. + - `"custom"` - - `text: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The text to type. + The tool invocation context(s). - - `type: "type"` + - `"direct"` - Specifies the event type. For a type action, this property is always set to `type`. + - `"programmatic"` - - `"type"` + - `defer_loading: optional boolean` - - `Wait object { type }` + Whether this tool should be deferred and discovered via tool search. - A wait action. + - `description: optional string` - - `type: "wait"` + Optional description of the custom tool, used to provide more context. - Specifies the event type. For a wait action, this property is always set to `wait`. + - `format: optional object { type } or object { definition, syntax, type }` - - `"wait"` + The input format for the custom tool. Default is unconstrained text. - - `actions: optional BetaComputerActionList` + - `Text object { type }` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + Unconstrained free-form text. - - `Click object { button, type, x, 2 more }` + - `type: "text"` - A click action. + Unconstrained text format. Always `text`. - - `DoubleClick object { keys, type, x, y }` + - `"text"` - A double click action. + - `Grammar object { definition, syntax, type }` - - `Drag object { path, type, keys }` + A grammar defined by the user. - A drag action. + - `definition: string` - - `Keypress object { keys, type }` + The grammar definition. - A collection of keypresses the model would like to perform. + - `syntax: "lark" or "regex"` - - `Move object { type, x, y, keys }` + The syntax of the grammar definition. One of `lark` or `regex`. - A mouse move action. + - `"lark"` - - `Screenshot object { type }` + - `"regex"` - A screenshot action. + - `type: "grammar"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + Grammar format. Always `grammar`. - A scroll action. + - `"grammar"` - - `Type object { text, type }` + - `Namespace object { description, name, tools, type }` - An action to type in text. + Groups function/custom tools under a shared namespace. - - `Wait object { type }` + - `description: string` - A wait action. + A description of the namespace shown to the model. - - `agent: optional object { agent_name }` + - `name: string` - The agent that produced this item. + The namespace name used in tool calls (for example, `crm`). - - `agent_name: string` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - The canonical name of the agent that produced this item. + The function/custom tools available inside this namespace. - - `ComputerCallOutput object { call_id, output, type, 4 more }` + - `Function object { name, type, allowed_callers, 5 more }` - The output of a computer tool call. + - `name: string` - - `call_id: string` + - `type: "function"` - The ID of the computer tool call that produced the output. + - `"function"` - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `allowed_callers: optional array of "direct" or "programmatic"` - A computer screenshot image used with the computer use tool. + The tool invocation context(s). - - `type: "computer_screenshot"` + - `"direct"` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `"programmatic"` - - `"computer_screenshot"` + - `defer_loading: optional boolean` - - `file_id: optional string` + Whether this function should be deferred and discovered via tool search. - The identifier of an uploaded file that contains the screenshot. + - `description: optional string` - - `image_url: optional string` + - `output_schema: optional map[unknown]` - The URL of the screenshot image. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `type: "computer_call_output"` + - `parameters: optional unknown` - The type of the computer tool call output. Always `computer_call_output`. + - `strict: optional boolean` - - `"computer_call_output"` + 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. - - `id: optional string` + - `Custom object { name, type, allowed_callers, 3 more }` - The ID of the computer tool call output. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `name: string` - The safety checks reported by the API that have been acknowledged by the developer. + The name of the custom tool, used to identify it in tool calls. - - `id: string` + - `type: "custom"` - The ID of the pending safety check. + The type of the custom tool. Always `custom`. - - `code: optional string` + - `"custom"` - 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"` - - `agent: optional object { agent_name }` + - `"programmatic"` - The agent that produced this item. + - `defer_loading: optional boolean` - - `agent_name: string` + Whether this tool should be deferred and discovered via tool search. - The canonical name of the agent that produced this item. + - `description: optional string` - - `status: optional "in_progress" or "completed" or "incomplete"` + Optional description of the custom tool, used to provide more context. - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `format: optional object { type } or object { definition, syntax, type }` - - `"in_progress"` + The input format for the custom tool. Default is unconstrained text. - - `"completed"` + - `Text object { type }` - - `"incomplete"` + Unconstrained free-form text. - - `WebSearchCall object { id, action, status, 2 more }` + - `type: "text"` - The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + Unconstrained text format. Always `text`. - - `id: string` + - `"text"` - The unique ID of the web search tool call. + - `Grammar object { definition, syntax, type }` - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + A grammar defined by the user. - 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). + - `definition: string` - - `Search object { type, queries, query, sources }` + The grammar definition. - Action type "search" - Performs a web search query. + - `syntax: "lark" or "regex"` - - `type: "search"` + The syntax of the grammar definition. One of `lark` or `regex`. - The action type. + - `"lark"` - - `"search"` + - `"regex"` - - `queries: optional array of string` + - `type: "grammar"` - The search queries. + Grammar format. Always `grammar`. - - `query: optional string` + - `"grammar"` - The search query. + - `type: "namespace"` - - `sources: optional array of object { type, url }` + The type of the tool. Always `namespace`. - The sources used in the search. + - `"namespace"` - - `type: "url"` + - `ToolSearch object { type, description, execution, parameters }` - The type of source. Always `url`. + Hosted or BYOT tool search configuration for deferred tools. - - `"url"` + - `type: "tool_search"` - - `url: string` + The type of the tool. Always `tool_search`. - The URL of the source. + - `"tool_search"` - - `OpenPage object { type, url }` + - `description: optional string` - Action type "open_page" - Opens a specific URL from search results. + Description shown to the model for a client-executed tool search tool. - - `type: "open_page"` + - `execution: optional "server" or "client"` - The action type. + Whether tool search is executed by the server or by the client. - - `"open_page"` + - `"server"` - - `url: optional string` + - `"client"` - The URL opened by the model. + - `parameters: optional unknown` - - `FindInPage object { pattern, type, url }` + Parameter schema for a client-executed tool search tool. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `pattern: 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 pattern or text to search for within the page. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `type: "find_in_page"` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The action type. + - `"web_search_preview"` - - `"find_in_page"` + - `"web_search_preview_2025_03_11"` - - `url: string` + - `search_content_types: optional array of "text" or "image"` - The URL of the page searched for the pattern. + - `"text"` - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `"image"` - The status of the web search tool call. + - `search_context_size: optional "low" or "medium" or "high"` - - `"in_progress"` + 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. - - `"searching"` + - `"low"` - - `"completed"` + - `"medium"` - - `"failed"` + - `"high"` - - `type: "web_search_call"` + - `user_location: optional object { type, city, country, 2 more }` - The type of the web search tool call. Always `web_search_call`. + The user's location. - - `"web_search_call"` + - `type: "approximate"` - - `agent: optional object { agent_name }` + The type of location approximation. Always `approximate`. - The agent that produced this item. + - `"approximate"` - - `agent_name: string` + - `city: optional string` - The canonical name of the agent that produced this item. + Free text input for the city of the user, e.g. `San Francisco`. - - `FunctionCall object { arguments, call_id, name, 6 more }` + - `country: optional string` - A tool call to run a function. See the - [function calling guide](/docs/guides/function-calling) for more information. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `arguments: string` + - `region: optional string` - A JSON string of the arguments to pass to the function. + Free text input for the region of the user, e.g. `California`. - - `call_id: string` + - `timezone: optional string` - The unique ID of the function tool call generated by the model. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `name: string` + - `ApplyPatch object { type, allowed_callers }` - The name of the function to run. + Allows the assistant to create, delete, or update files using unified diffs. - - `type: "function_call"` + - `type: "apply_patch"` - The type of the function tool call. Always `function_call`. + The type of the tool. Always `apply_patch`. - - `"function_call"` + - `"apply_patch"` - - `id: optional string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The unique ID of the function tool call. + The tool invocation context(s). - - `agent: optional object { agent_name }` + - `"direct"` - The agent that produced this item. + - `"programmatic"` - - `agent_name: string` + - `type: "tool_search_output"` - The canonical name of the agent that produced this item. + The item type. Always `tool_search_output`. - - `caller: optional object { type } or object { caller_id, type }` + - `"tool_search_output"` - The execution context that produced this tool call. + - `id: optional string` - - `Direct object { type }` + The unique ID of this tool search output. - - `type: "direct"` + - `agent: optional object { agent_name }` - - `"direct"` + The agent that produced this item. - - `Program object { caller_id, type }` + - `agent_name: string` - - `caller_id: string` + The canonical name of the agent that produced this item. - The call ID of the program item that produced this tool call. + - `call_id: optional string` - - `type: "program"` + The unique ID of the tool search call generated by the model. - - `"program"` + - `execution: optional "server" or "client"` - - `namespace: optional string` + Whether tool search was executed by the server or by the client. - The namespace of the function to run. + - `"server"` + + - `"client"` - `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 tool search output. - `"in_progress"` @@ -30622,588 +32026,136 @@ the `background` parameter set to `true` can be cancelled. - `"incomplete"` - - `FunctionCallOutput object { call_id, output, type, 4 more }` + - `AdditionalTools object { role, tools, type, 2 more }` - The output of a function tool call. + - `role: "developer"` - - `call_id: string` + The role that provided the additional tools. Only `developer` is supported. - The unique ID of the function tool call generated by the model. + - `"developer"` - - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - Text, image, or file output of the function tool call. + A list of additional tools made available at this item. - - `string` + - `Function object { name, parameters, strict, 5 more }` - A JSON string of the output of the function tool call. + 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). - - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` + - `name: string` - An array of content outputs (text, image, file) for the function tool call. + The name of the function to call. - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + - `parameters: map[unknown]` - A text input to the model. + A JSON schema object describing the parameters of the function. - - `text: string` + - `strict: boolean` - The text input to the model. + Whether strict parameter validation is enforced for this function tool. - - `type: "input_text"` + - `type: "function"` - The type of the input item. Always `input_text`. + The type of the function tool. Always `function`. - - `"input_text"` + - `"function"` - - `prompt_cache_breakpoint: optional object { mode }` + - `allowed_callers: optional array of "direct" or "programmatic"` - 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 tool invocation context(s). - - `mode: "explicit"` + - `"direct"` - The breakpoint mode. Always `explicit`. + - `"programmatic"` - - `"explicit"` + - `defer_loading: optional boolean` - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + Whether this function is deferred and loaded via tool search. - An image input to the model. Learn about [image inputs](/docs/guides/vision) + - `description: optional string` - - `type: "input_image"` + A description of the function. Used by the model to determine whether or not to call the function. - The type of the input item. Always `input_image`. + - `output_schema: optional map[unknown]` - - `"input_image"` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `detail: optional "low" or "high" or "auto" or "original"` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `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). - - `"low"` + - `type: "file_search"` - - `"high"` + The type of the file search tool. Always `file_search`. - - `"auto"` + - `"file_search"` - - `"original"` + - `vector_store_ids: array of string` - - `file_id: optional string` + The IDs of the vector stores to search. - The ID of the file to be sent to the model. + - `filters: optional object { key, type, value } or object { filters, type }` - - `image_url: optional string` + A filter to apply. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `ComparisonFilter object { key, type, value }` - - `prompt_cache_breakpoint: optional object { mode }` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - 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. + - `key: string` - - `mode: "explicit"` + The key to compare against the value. - The breakpoint mode. Always `explicit`. + - `type: "eq" or "ne" or "gt" or 5 more` - - `"explicit"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - A file input to the model. + - `"eq"` - - `type: "input_file"` + - `"ne"` - The type of the input item. Always `input_file`. + - `"gt"` - - `"input_file"` + - `"gte"` - - `detail: optional "auto" or "low" or "high"` + - `"lt"` - 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`. + - `"lte"` - - `"auto"` + - `"in"` - - `"low"` + - `"nin"` - - `"high"` + - `value: string or number or boolean or array of string or number` - - `file_data: optional string` + The value to compare against the attribute key; supports string, number, or boolean types. - The base64-encoded data of the file to be sent to the model. + - `string` - - `file_id: optional string` + - `number` - The ID of the file to be sent to the model. + - `boolean` - - `file_url: optional string` + - `array of string or number` - The URL of the file to be sent to the model. + - `string` - - `filename: optional string` + - `number` - The name of the file to be sent to the model. + - `CompoundFilter object { filters, type }` - - `prompt_cache_breakpoint: optional object { mode }` + Combine multiple filters using `and` or `or`. - 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. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `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"` - - - `AgentMessage object { author, content, recipient, 3 more }` - - A message routed between agents. - - - `author: string` - - The sending agent identity. - - - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - - Plaintext, image, or encrypted content sent between agents. - - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](/docs/guides/vision) - - - `EncryptedContent object { encrypted_content, type }` - - Opaque encrypted content that Responses API decrypts inside trusted model execution. - - - `encrypted_content: string` - - Opaque encrypted content. - - - `type: "encrypted_content"` - - The type of the input item. Always `encrypted_content`. - - - `"encrypted_content"` - - - `recipient: string` - - The destination agent identity. - - - `type: "agent_message"` - - The item type. Always `agent_message`. - - - `"agent_message"` - - - `id: optional string` - - The unique ID of this agent message item. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `MultiAgentCall object { action, arguments, call_id, 3 more }` - - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - The multi-agent action that was executed. - - - `"spawn_agent"` - - - `"interrupt_agent"` - - - `"list_agents"` - - - `"send_message"` - - - `"followup_task"` - - - `"wait_agent"` - - - `arguments: string` - - The action arguments as a JSON string. - - - `call_id: string` - - The unique ID linking this call to its output. - - - `type: "multi_agent_call"` - - The item type. Always `multi_agent_call`. - - - `"multi_agent_call"` - - - `id: optional string` - - The unique ID of this multi-agent call. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `MultiAgentCallOutput object { action, call_id, output, 3 more }` - - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - The multi-agent action that produced this result. - - - `"spawn_agent"` - - - `"interrupt_agent"` - - - `"list_agents"` - - - `"send_message"` - - - `"followup_task"` - - - `"wait_agent"` - - - `call_id: string` - - The unique ID of the multi-agent call. - - - `output: array of object { text, type, annotations }` - - Text output returned by the multi-agent action. - - - `text: string` - - The text content. - - - `type: "output_text"` - - The content type. Always `output_text`. - - - `"output_text"` - - - `annotations: optional 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 }` - - Citations associated with the text content. - - - `FileCitation object { file_id, filename, index, type }` - - - `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 citation type. Always `file_citation`. - - - `"file_citation"` - - - `URLCitation object { end_index, start_index, title, 2 more }` - - - `end_index: number` - - The index of the last character of the citation in the message. - - - `start_index: number` - - The index of the first character of the citation in the message. - - - `title: string` - - The title of the cited resource. - - - `type: "url_citation"` - - The citation type. Always `url_citation`. - - - `"url_citation"` - - - `url: string` - - The URL of the cited resource. - - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - - - `container_id: string` - - The ID of the container. - - - `end_index: number` - - The index of the last character of the citation in the message. - - - `file_id: string` - - The ID of the container file. - - - `filename: string` - - The filename of the container file cited. - - - `start_index: number` - - The index of the first character of the citation in the message. - - - `type: "container_file_citation"` - - The citation type. Always `container_file_citation`. - - - `"container_file_citation"` - - - `type: "multi_agent_call_output"` - - The item type. Always `multi_agent_call_output`. - - - `"multi_agent_call_output"` - - - `id: optional string` - - The unique ID of this multi-agent call output. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `ToolSearchCall object { arguments, type, id, 4 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. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `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, 4 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 object { key, type, value } or object { filters, type }` - - 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 object { key, type, value } or unknown` + - `filters: array of object { key, type, value } or unknown` Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. @@ -31605,40 +32557,8 @@ the `background` parameter set to `true` can be cancelled. - `BetaContainerNetworkPolicyDisabled object { type }` - - `type: "disabled"` - - Disable outbound network access. Always `disabled`. - - - `"disabled"` - - `BetaContainerNetworkPolicyAllowlist 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 BetaContainerNetworkPolicyDomainSecret` - - 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`. @@ -31819,128 +32739,10 @@ the `background` parameter set to `true` can be cancelled. - `BetaContainerAuto 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 BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - Network access policy for the container. - - - `BetaContainerNetworkPolicyDisabled object { type }` - - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - - `skills: optional array of BetaSkillReference or BetaInlineSkill` - - An optional list of skills referenced by id or inline data. - - - `BetaSkillReference 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. - - - `BetaInlineSkill object { description, name, source, type }` - - - `description: string` - - The description of the skill. - - - `name: string` - - The name of the skill. - - - `source: BetaInlineSkillSource` - - 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"` - - `BetaLocalEnvironment object { type, skills }` - - `type: "local"` - - Use a local computer environment. - - - `"local"` - - - `skills: optional array of BetaLocalSkill` - - 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. - - `BetaContainerReference 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) @@ -32225,15 +33027,15 @@ the `background` parameter set to `true` can be cancelled. - `"programmatic"` - - `type: "tool_search_output"` + - `type: "additional_tools"` - The item type. Always `tool_search_output`. + The item type. Always `additional_tools`. - - `"tool_search_output"` + - `"additional_tools"` - `id: optional string` - The unique ID of this tool search output. + The unique ID of this additional tools item. - `agent: optional object { agent_name }` @@ -32243,1038 +33045,960 @@ the `background` parameter set to `true` can be cancelled. The canonical name of the agent that produced this item. - - `call_id: optional string` + - `Reasoning object { id, summary, type, 4 more }` - The unique ID of the tool search call generated by the model. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](/docs/guides/conversation-state). - - `execution: optional "server" or "client"` + - `id: string` - Whether tool search was executed by the server or by the client. + The unique identifier of the reasoning content. - - `"server"` + - `summary: array of object { text, type }` - - `"client"` + Reasoning summary content. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `text: string` - The status of the tool search output. + A summary of the reasoning output from the model so far. - - `"in_progress"` + - `type: "summary_text"` - - `"completed"` + The type of the object. Always `summary_text`. - - `"incomplete"` + - `"summary_text"` - - `AdditionalTools object { role, tools, type, 2 more }` + - `type: "reasoning"` - - `role: "developer"` + The type of the object. Always `reasoning`. - The role that provided the additional tools. Only `developer` is supported. + - `"reasoning"` - - `"developer"` + - `agent: optional object { agent_name }` - - `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 agent that produced this item. - A list of additional tools made available at this item. + - `agent_name: string` - - `Function object { name, parameters, strict, 5 more }` + The canonical name of the agent that produced this item. - 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). + - `content: optional array of object { text, type }` - - `name: string` + Reasoning text content. - The name of the function to call. + - `text: string` - - `parameters: map[unknown]` + The reasoning text from the model. - A JSON schema object describing the parameters of the function. + - `type: "reasoning_text"` - - `strict: boolean` + The type of the reasoning text. Always `reasoning_text`. - Whether strict parameter validation is enforced for this function tool. + - `"reasoning_text"` - - `type: "function"` + - `encrypted_content: optional string` - The type of the function tool. Always `function`. + 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. - - `"function"` + - `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`. Populated when items are returned via API. - The tool invocation context(s). + - `"in_progress"` - - `"direct"` + - `"completed"` - - `"programmatic"` + - `"incomplete"` - - `defer_loading: optional boolean` + - `Compaction object { encrypted_content, type, id, agent }` - Whether this function is deferred and loaded via tool search. + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - - `description: optional string` + - `encrypted_content: string` - A description of the function. Used by the model to determine whether or not to call the function. + The encrypted content of the compaction summary. - - `output_schema: optional map[unknown]` + - `type: "compaction"` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The type of the item. Always `compaction`. - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `"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). + - `id: optional string` - - `type: "file_search"` + The ID of the compaction item. - The type of the file search tool. Always `file_search`. + - `agent: optional object { agent_name }` - - `"file_search"` + The agent that produced this item. - - `vector_store_ids: array of string` + - `agent_name: string` - The IDs of the vector stores to search. + The canonical name of the agent that produced this item. - - `filters: optional object { key, type, value } or object { filters, type }` + - `ImageGenerationCall object { id, result, status, 2 more }` - A filter to apply. + An image generation request made by the model. - - `ComparisonFilter object { key, type, value }` + - `id: string` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The unique ID of the image generation call. - - `key: string` + - `result: string` - The key to compare against the value. + The generated image encoded in base64. - - `type: "eq" or "ne" or "gt" or 5 more` + - `status: "in_progress" or "completed" or "generating" or "failed"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The status of the image generation 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 + - `"in_progress"` - - `"eq"` + - `"completed"` - - `"ne"` + - `"generating"` - - `"gt"` + - `"failed"` - - `"gte"` + - `type: "image_generation_call"` - - `"lt"` + The type of the image generation call. Always `image_generation_call`. - - `"lte"` + - `"image_generation_call"` - - `"in"` + - `agent: optional object { agent_name }` - - `"nin"` + The agent that produced this item. - - `value: string or number or boolean or array of string or number` + - `agent_name: string` - The value to compare against the attribute key; supports string, number, or boolean types. + The canonical name of the agent that produced this item. - - `string` + - `CodeInterpreterCall object { id, code, container_id, 4 more }` - - `number` + A tool call to run code. - - `boolean` + - `id: string` - - `array of string or number` + The unique ID of the code interpreter tool call. - - `string` + - `code: string` - - `number` + The code to run, or null if not available. - - `CompoundFilter object { filters, type }` + - `container_id: string` - Combine multiple filters using `and` or `or`. + The ID of the container used to run the code. - - `filters: array of object { key, type, value } or unknown` + - `outputs: array of object { logs, type } or object { type, url }` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `ComparisonFilter object { key, type, value }` + - `Logs object { logs, type }` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The logs output from the code interpreter. - - `key: string` + - `logs: string` - The key to compare against the value. + The logs output from the code interpreter. - - `type: "eq" or "ne" or "gt" or 5 more` + - `type: "logs"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The type of the output. Always `logs`. - - `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 + - `"logs"` - - `"eq"` + - `Image object { type, url }` - - `"ne"` + The image output from the code interpreter. - - `"gt"` + - `type: "image"` - - `"gte"` + The type of the output. Always `image`. - - `"lt"` + - `"image"` - - `"lte"` + - `url: string` - - `"in"` + The URL of the image output from the code interpreter. - - `"nin"` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - `value: string or number or boolean or array of string or number` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - The value to compare against the attribute key; supports string, number, or boolean types. + - `"in_progress"` - - `string` + - `"completed"` - - `number` + - `"incomplete"` - - `boolean` + - `"interpreting"` - - `array of string or number` + - `"failed"` - - `string` + - `type: "code_interpreter_call"` - - `number` + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `unknown` + - `"code_interpreter_call"` - - `type: "and" or "or"` + - `agent: optional object { agent_name }` - Type of operation: `and` or `or`. + The agent that produced this item. - - `"and"` + - `agent_name: string` - - `"or"` + The canonical name of the agent that produced this item. - - `max_num_results: optional number` + - `LocalShellCall object { id, action, call_id, 3 more }` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + A tool call to run a command on the local shell. - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `id: string` - Ranking options for search. + The unique ID of the local shell call. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `action: object { command, env, type, 3 more }` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + Execute a shell command on the server. - - `embedding_weight: number` + - `command: array of string` - The weight of the embedding in the reciprocal ranking fusion. + The command to run. - - `text_weight: number` + - `env: map[string]` - The weight of the text in the reciprocal ranking fusion. + Environment variables to set for the command. - - `ranker: optional "auto" or "default-2024-11-15"` + - `type: "exec"` - The ranker to use for the file search. + The type of the local shell action. Always `exec`. - - `"auto"` + - `"exec"` - - `"default-2024-11-15"` + - `timeout_ms: optional number` - - `score_threshold: optional number` + Optional timeout in milliseconds for the command. - 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. + - `user: optional string` - - `Computer object { type }` + Optional user to run the command as. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `working_directory: optional string` - - `type: "computer"` + Optional working directory to run the command in. - The type of the computer tool. Always `computer`. + - `call_id: string` - - `"computer"` + The unique ID of the local shell tool call generated by the model. - - `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 local shell call. - - `display_height: number` + - `"in_progress"` - The height of the computer display. + - `"completed"` - - `display_width: number` + - `"incomplete"` - The width of the computer display. + - `type: "local_shell_call"` - - `environment: "windows" or "mac" or "linux" or 2 more` + The type of the local shell call. Always `local_shell_call`. - The type of computer environment to control. + - `"local_shell_call"` - - `"windows"` + - `agent: optional object { agent_name }` - - `"mac"` + The agent that produced this item. - - `"linux"` + - `agent_name: string` - - `"ubuntu"` + The canonical name of the agent that produced this item. - - `"browser"` + - `LocalShellCallOutput object { id, output, type, 2 more }` - - `type: "computer_use_preview"` + The output of a local shell tool call. - The type of the computer use tool. Always `computer_use_preview`. + - `id: string` - - `"computer_use_preview"` + The unique ID of the local shell tool call generated by the model. - - `WebSearch object { type, filters, search_context_size, user_location }` + - `output: string` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + A JSON string of the output of the local shell tool call. - - `type: "web_search" or "web_search_2025_08_26"` + - `type: "local_shell_call_output"` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `"web_search"` + - `"local_shell_call_output"` - - `"web_search_2025_08_26"` + - `agent: optional object { agent_name }` - - `filters: optional object { allowed_domains }` + The agent that produced this item. - Filters for the search. + - `agent_name: string` - - `allowed_domains: optional array of string` + The canonical name of the agent that produced this item. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `status: optional "in_progress" or "completed" or "incomplete"` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `search_context_size: optional "low" or "medium" or "high"` + - `"in_progress"` - 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. + - `"completed"` - - `"low"` + - `"incomplete"` - - `"medium"` + - `ShellCall object { action, call_id, type, 5 more }` - - `"high"` + A tool representing a request to execute one or more shell commands. - - `user_location: optional object { city, country, region, 2 more }` + - `action: object { commands, max_output_length, timeout_ms }` - The approximate location of the user. + The shell commands and limits that describe how to run the tool call. - - `city: optional string` + - `commands: array of string` - Free text input for the city of the user, e.g. `San Francisco`. + Ordered shell commands for the execution environment to run. - - `country: optional string` + - `max_output_length: optional number` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `region: optional string` + - `timeout_ms: optional number` - Free text input for the region of the user, e.g. `California`. + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `timezone: optional string` + - `call_id: string` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The unique ID of the shell tool call generated by the model. - - `type: optional "approximate"` + - `type: "shell_call"` - The type of location approximation. Always `approximate`. + The type of the item. Always `shell_call`. - - `"approximate"` + - `"shell_call"` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `id: optional string` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + The unique ID of the shell tool call. Populated when this item is returned via API. - - `server_label: string` + - `agent: optional object { agent_name }` - A label for this MCP server, used to identify it in tool calls. + The agent that produced this item. - - `type: "mcp"` + - `agent_name: string` - The type of the MCP tool. Always `mcp`. + The canonical name of the agent that produced this item. - - `"mcp"` + - `caller: optional object { type } or object { caller_id, type }` - - `allowed_callers: optional array of "direct" or "programmatic"` + The execution context that produced this tool call. - The tool invocation context(s). + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. - `"direct"` - - `"programmatic"` + - `Program object { caller_id, type }` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `caller_id: string` - List of allowed tool names or a filter object. + The call ID of the program item that produced this tool call. - - `McpAllowedTools = array of string` + - `type: "program"` - A string array of allowed tool names + The caller type. Always `program`. - - `McpToolFilter object { read_only, tool_names }` + - `"program"` - A filter object to specify which tools are allowed. + - `environment: optional BetaLocalEnvironment or BetaContainerReference` - - `read_only: optional boolean` + The environment to execute the shell commands in. - 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. + - `BetaLocalEnvironment object { type, skills }` - - `tool_names: optional array of string` + - `BetaContainerReference object { container_id, type }` - List of allowed tool names. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `authorization: optional string` + The status of the shell call. One of `in_progress`, `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. - - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). - - Currently supported `connector_id` values are: - - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` - - - `"connector_dropbox"` - - - `"connector_gmail"` + - `"in_progress"` - - `"connector_googlecalendar"` + - `"completed"` - - `"connector_googledrive"` + - `"incomplete"` - - `"connector_microsoftteams"` + - `ShellCallOutput object { call_id, output, type, 5 more }` - - `"connector_outlookcalendar"` + The streamed output items emitted by a shell tool call. - - `"connector_outlookemail"` + - `call_id: string` - - `"connector_sharepoint"` + The unique ID of the shell tool call generated by the model. - - `defer_loading: optional boolean` + - `output: array of BetaResponseFunctionShellCallOutputContent` - Whether this MCP tool is deferred and discovered via tool search. + Captured chunks of stdout and stderr output, along with their associated outcomes. - - `headers: optional map[string]` + - `outcome: object { type } or object { exit_code, type }` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The exit or timeout outcome associated with this shell call. - - `require_approval: optional object { always, never } or "always" or "never"` + - `Timeout object { type }` - Specify which of the MCP server's tools require approval. + Indicates that the shell call exceeded its configured time limit. - - `McpToolApprovalFilter object { always, never }` + - `type: "timeout"` - 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 outcome type. Always `timeout`. - - `always: optional object { read_only, tool_names }` + - `"timeout"` - A filter object to specify which tools are allowed. + - `Exit object { exit_code, type }` - - `read_only: optional boolean` + Indicates that the shell commands finished and returned an exit code. - 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. + - `exit_code: number` - - `tool_names: optional array of string` + The exit code returned by the shell process. - List of allowed tool names. + - `type: "exit"` - - `never: optional object { read_only, tool_names }` + The outcome type. Always `exit`. - A filter object to specify which tools are allowed. + - `"exit"` - - `read_only: optional boolean` + - `stderr: 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. + Captured stderr output for the shell call. - - `tool_names: optional array of string` + - `stdout: string` - List of allowed tool names. + Captured stdout output for the shell call. - - `McpToolApprovalSetting = "always" or "never"` + - `type: "shell_call_output"` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + The type of the item. Always `shell_call_output`. - - `"always"` + - `"shell_call_output"` - - `"never"` + - `id: optional string` - - `server_description: optional string` + The unique ID of the shell tool call output. Populated when this item is returned via API. - Optional description of the MCP server, used to provide more context. + - `agent: optional object { agent_name }` - - `server_url: optional string` + The agent that produced this item. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `agent_name: string` - - `tunnel_id: optional string` + The canonical name of the agent that produced this item. - 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. + - `caller: optional object { type } or object { caller_id, type }` - - `CodeInterpreter object { container, type, allowed_callers }` + The execution context that produced this tool call. - A tool that runs Python code to help generate a response to a prompt. + - `Direct object { type }` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `type: "direct"` - 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 caller type. Always `direct`. - - `string` + - `"direct"` - The container ID. + - `Program object { caller_id, type }` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `caller_id: string` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + The call ID of the program item that produced this tool call. - - `type: "auto"` + - `type: "program"` - Always `auto`. + The caller type. Always `program`. - - `"auto"` + - `"program"` - - `file_ids: optional array of string` + - `max_output_length: optional number` - An optional list of uploaded files to make available to your code. + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `status: optional "in_progress" or "completed" or "incomplete"` - The memory limit for the code interpreter container. + The status of the shell call output. - - `"1g"` + - `"in_progress"` - - `"4g"` + - `"completed"` - - `"16g"` + - `"incomplete"` - - `"64g"` + - `ApplyPatchCall object { call_id, operation, status, 4 more }` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + A tool call representing a request to create, delete, or update files using diff patches. - Network access policy for the container. + - `call_id: string` - - `BetaContainerNetworkPolicyDisabled object { type }` + The unique ID of the apply patch tool call generated by the model. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - `type: "code_interpreter"` + The specific create, delete, or update instruction for the apply_patch tool call. - The type of the code interpreter tool. Always `code_interpreter`. + - `CreateFile object { diff, path, type }` - - `"code_interpreter"` + Instruction for creating a new file via the apply_patch tool. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `diff: string` - The tool invocation context(s). + Unified diff content to apply when creating the file. - - `"direct"` + - `path: string` - - `"programmatic"` + Path of the file to create relative to the workspace root. - - `ProgrammaticToolCalling object { type }` + - `type: "create_file"` - - `type: "programmatic_tool_calling"` + The operation type. Always `create_file`. - The type of the tool. Always `programmatic_tool_calling`. + - `"create_file"` - - `"programmatic_tool_calling"` + - `DeleteFile object { path, type }` - - `ImageGeneration object { type, action, background, 9 more }` + Instruction for deleting an existing file via the apply_patch tool. - A tool that generates images using the GPT image models. + - `path: string` - - `type: "image_generation"` + Path of the file to delete relative to the workspace root. - The type of the image generation tool. Always `image_generation`. + - `type: "delete_file"` - - `"image_generation"` + The operation type. Always `delete_file`. - - `action: optional "generate" or "edit" or "auto"` + - `"delete_file"` - Whether to generate a new image or edit an existing image. Default: `auto`. + - `UpdateFile object { diff, path, type }` - - `"generate"` + Instruction for updating an existing file via the apply_patch tool. - - `"edit"` + - `diff: string` - - `"auto"` + Unified diff content to apply to the existing 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 update relative to the workspace root. - - `"transparent"` + - `type: "update_file"` - - `"opaque"` + The operation type. Always `update_file`. - - `"auto"` + - `"update_file"` - - `input_fidelity: optional "high" or "low"` + - `status: "in_progress" or "completed"` - 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 apply patch tool call. One of `in_progress` or `completed`. - - `"high"` + - `"in_progress"` - - `"low"` + - `"completed"` - - `input_image_mask: optional object { file_id, image_url }` + - `type: "apply_patch_call"` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + The type of the item. Always `apply_patch_call`. - - `file_id: optional string` + - `"apply_patch_call"` - File ID for the mask image. + - `id: optional string` - - `image_url: optional string` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - Base64-encoded mask image. + - `agent: optional object { agent_name }` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + The agent that produced this item. - The image generation model to use. Default: `gpt-image-1`. + - `agent_name: string` - - `string` + The canonical name of the agent that produced this item. - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `caller: optional object { type } or object { caller_id, type }` - The image generation model to use. Default: `gpt-image-1`. + The execution context that produced this tool call. - - `"gpt-image-1"` + - `Direct object { type }` - - `"gpt-image-1-mini"` + - `type: "direct"` - - `"gpt-image-1.5"` + The caller type. Always `direct`. - - `moderation: optional "auto" or "low"` + - `"direct"` - Moderation level for the generated image. Default: `auto`. + - `Program object { caller_id, type }` - - `"auto"` + - `caller_id: string` - - `"low"` + The call ID of the program item that produced this tool call. - - `output_compression: optional number` + - `type: "program"` - Compression level for the output image. Default: 100. + The caller type. Always `program`. - - `output_format: optional "png" or "webp" or "jpeg"` + - `"program"` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` - - `"png"` + The streamed output emitted by an apply patch tool call. - - `"webp"` + - `call_id: string` - - `"jpeg"` + The unique ID of the apply patch tool call generated by the model. - - `partial_images: optional number` + - `status: "completed" or "failed"` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `"completed"` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `"failed"` - - `"low"` + - `type: "apply_patch_call_output"` - - `"medium"` + The type of the item. Always `apply_patch_call_output`. - - `"high"` + - `"apply_patch_call_output"` - - `"auto"` + - `id: optional string` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - 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`. + - `agent: optional object { agent_name }` - - `string` + The agent that produced this item. - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `agent_name: string` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + The canonical name of the agent that produced this item. - - `"1024x1024"` + - `caller: optional object { type } or object { caller_id, type }` - - `"1024x1536"` + The execution context that produced this tool call. - - `"1536x1024"` + - `Direct object { type }` - - `"auto"` + - `type: "direct"` - - `LocalShell object { type }` + The caller type. Always `direct`. - A tool that allows the model to execute shell commands in a local environment. + - `"direct"` - - `type: "local_shell"` + - `Program object { caller_id, type }` - The type of the local shell tool. Always `local_shell`. + - `caller_id: string` - - `"local_shell"` + The call ID of the program item that produced this tool call. - - `Shell object { type, allowed_callers, environment }` + - `type: "program"` - A tool that allows the model to execute shell commands. + The caller type. Always `program`. - - `type: "shell"` + - `"program"` - The type of the shell tool. Always `shell`. + - `output: optional string` - - `"shell"` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - `allowed_callers: optional array of "direct" or "programmatic"` + - `McpListTools object { id, server_label, tools, 3 more }` - The tool invocation context(s). + A list of tools available on an MCP server. - - `"direct"` + - `id: string` - - `"programmatic"` + The unique ID of the list. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `server_label: string` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + The label of the MCP server. - - `BetaLocalEnvironment object { type, skills }` + - `tools: array of object { input_schema, name, annotations, description }` - - `BetaContainerReference object { container_id, type }` + The tools available on the server. - - `Custom object { name, type, allowed_callers, 3 more }` + - `input_schema: unknown` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + The JSON schema describing the tool's input. - `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"` + The name of the tool. - - `defer_loading: optional boolean` + - `annotations: optional unknown` - Whether this tool should be deferred and discovered via tool search. + Additional annotations about the tool. - `description: optional string` - Optional description of the custom tool, used to provide more context. - - - `format: optional object { type } or object { definition, syntax, type }` - - 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"` + The description of the tool. - - `Grammar object { definition, syntax, type }` + - `type: "mcp_list_tools"` - A grammar defined by the user. + The type of the item. Always `mcp_list_tools`. - - `definition: string` + - `"mcp_list_tools"` - The grammar definition. + - `agent: optional object { agent_name }` - - `syntax: "lark" or "regex"` + The agent that produced this item. - The syntax of the grammar definition. One of `lark` or `regex`. + - `agent_name: string` - - `"lark"` + The canonical name of the agent that produced this item. - - `"regex"` + - `error: optional string` - - `type: "grammar"` + Error message if the server could not list tools. - Grammar format. Always `grammar`. + - `McpApprovalRequest object { id, arguments, name, 3 more }` - - `"grammar"` + A request for human approval of a tool invocation. - - `Namespace object { description, name, tools, type }` + - `id: string` - Groups function/custom tools under a shared namespace. + The unique ID of the approval request. - - `description: string` + - `arguments: string` - A description of the namespace shown to the model. + A JSON string of arguments for the tool. - `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. + The name of the tool to run. - - `Function object { name, type, allowed_callers, 5 more }` + - `server_label: string` - - `name: string` + The label of the MCP server making the request. - - `type: "function"` + - `type: "mcp_approval_request"` - - `"function"` + The type of the item. Always `mcp_approval_request`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"mcp_approval_request"` - The tool invocation context(s). + - `agent: optional object { agent_name }` - - `"direct"` + The agent that produced this item. - - `"programmatic"` + - `agent_name: string` - - `defer_loading: optional boolean` + The canonical name of the agent that produced this item. - Whether this function should be deferred and discovered via tool search. + - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` - - `description: optional string` + A response to an MCP approval request. - - `output_schema: optional map[unknown]` + - `approval_request_id: string` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + The ID of the approval request being answered. - - `parameters: optional unknown` + - `approve: boolean` - - `strict: optional boolean` + Whether the request was approved. - 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: "mcp_approval_response"` - - `Custom object { name, type, allowed_callers, 3 more }` + The type of the item. Always `mcp_approval_response`. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `"mcp_approval_response"` - - `name: string` + - `id: optional string` - The name of the custom tool, used to identify it in tool calls. + The unique ID of the approval response - - `type: "custom"` + - `agent: optional object { agent_name }` - The type of the custom tool. Always `custom`. + The agent that produced this item. - - `"custom"` + - `agent_name: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The canonical name of the agent that produced this item. - The tool invocation context(s). + - `reason: optional string` - - `"direct"` + Optional reason for the decision. - - `"programmatic"` + - `McpCall object { id, arguments, name, 7 more }` - - `defer_loading: optional boolean` + An invocation of a tool on an MCP server. - Whether this tool should be deferred and discovered via tool search. + - `id: string` - - `description: optional string` + The unique ID of the tool call. - Optional description of the custom tool, used to provide more context. + - `arguments: string` - - `format: optional object { type } or object { definition, syntax, type }` + A JSON string of the arguments passed to the tool. - The input format for the custom tool. Default is unconstrained text. + - `name: string` - - `Text object { type }` + The name of the tool that was run. - Unconstrained free-form text. + - `server_label: string` - - `type: "text"` + The label of the MCP server running the tool. - Unconstrained text format. Always `text`. + - `type: "mcp_call"` - - `"text"` + The type of the item. Always `mcp_call`. - - `Grammar object { definition, syntax, type }` + - `"mcp_call"` - A grammar defined by the user. + - `agent: optional object { agent_name }` - - `definition: string` + The agent that produced this item. - The grammar definition. + - `agent_name: string` - - `syntax: "lark" or "regex"` + The canonical name of the agent that produced this item. - The syntax of the grammar definition. One of `lark` or `regex`. + - `approval_request_id: optional string` - - `"lark"` + 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. - - `"regex"` + - `error: optional string` - - `type: "grammar"` + The error from the tool call, if any. - Grammar format. Always `grammar`. + - `output: optional string` - - `"grammar"` + The output from the tool call. - - `type: "namespace"` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - The type of the tool. Always `namespace`. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `"namespace"` + - `"in_progress"` - - `ToolSearch object { type, description, execution, parameters }` + - `"completed"` - Hosted or BYOT tool search configuration for deferred tools. + - `"incomplete"` - - `type: "tool_search"` + - `"calling"` - The type of the tool. Always `tool_search`. + - `"failed"` - - `"tool_search"` + - `CustomToolCallOutput object { call_id, output, type, 3 more }` - - `description: optional string` + The output of a custom tool call from your code, being sent back to the model. - Description shown to the model for a client-executed tool search tool. + - `call_id: string` - - `execution: optional "server" or "client"` + The call ID, used to map this custom tool call output to a custom tool call. - Whether tool search is executed by the server or by the client. + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `"server"` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `"client"` + - `StringOutput = string` - - `parameters: optional unknown` + A string of the output of the custom tool call. - Parameter schema for a client-executed tool search tool. + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + Text, image, or file output of the custom tool call. - 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). + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + A text input to the model. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `"web_search_preview"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"web_search_preview_2025_03_11"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `search_content_types: optional array of "text" or "image"` + A file input to the model. - - `"text"` + - `type: "custom_tool_call_output"` - - `"image"` + The type of the custom tool call output. Always `custom_tool_call_output`. - - `search_context_size: optional "low" or "medium" or "high"` + - `"custom_tool_call_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. + - `id: optional string` - - `"low"` + The unique ID of the custom tool call output in the OpenAI platform. - - `"medium"` + - `agent: optional object { agent_name }` - - `"high"` + The agent that produced this item. - - `user_location: optional object { type, city, country, 2 more }` + - `agent_name: string` - The user's location. + The canonical name of the agent that produced this item. - - `type: "approximate"` + - `caller: optional object { type } or object { caller_id, type }` - The type of location approximation. Always `approximate`. + The execution context that produced this tool call. - - `"approximate"` + - `Direct object { type }` - - `city: optional string` + - `type: "direct"` - Free text input for the city of the user, e.g. `San Francisco`. + The caller type. Always `direct`. - - `country: optional string` + - `"direct"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `Program object { caller_id, type }` - - `region: optional string` + - `caller_id: string` - Free text input for the region of the user, e.g. `California`. + The call ID of the program item that produced this tool call. - - `timezone: optional string` + - `type: "program"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The caller type. Always `program`. - - `ApplyPatch object { type, allowed_callers }` + - `"program"` - Allows the assistant to create, delete, or update files using unified diffs. + - `CustomToolCall object { call_id, input, name, 5 more }` - - `type: "apply_patch"` + A call to a custom tool created by the model. - The type of the tool. Always `apply_patch`. + - `call_id: string` - - `"apply_patch"` + An identifier used to map this custom tool call to a tool call output. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `input: string` - The tool invocation context(s). + The input for the custom tool call generated by the model. - - `"direct"` + - `name: string` - - `"programmatic"` + The name of the custom tool being called. - - `type: "additional_tools"` + - `type: "custom_tool_call"` - The item type. Always `additional_tools`. + The type of the custom tool call. Always `custom_tool_call`. - - `"additional_tools"` + - `"custom_tool_call"` - `id: optional string` - The unique ID of this additional tools item. + The unique ID of the custom tool call in the OpenAI platform. - `agent: optional object { agent_name }` @@ -33284,36 +34008,39 @@ the `background` parameter set to `true` can be cancelled. The canonical name of the agent that produced this item. - - `Reasoning object { id, summary, type, 4 more }` + - `caller: optional object { type } or object { caller_id, type }` - 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 execution context that produced this tool call. - - `id: string` + - `Direct object { type }` - The unique identifier of the reasoning content. + - `type: "direct"` - - `summary: array of object { text, type }` + - `"direct"` - Reasoning summary content. + - `Program object { caller_id, type }` - - `text: string` + - `caller_id: string` - A summary of the reasoning output from the model so far. + The call ID of the program item that produced this tool call. - - `type: "summary_text"` + - `type: "program"` - The type of the object. Always `summary_text`. + - `"program"` - - `"summary_text"` + - `namespace: optional string` - - `type: "reasoning"` + The namespace of the custom tool being called. - The type of the object. Always `reasoning`. + - `CompactionTrigger object { type, agent }` - - `"reasoning"` + Compacts the current context. Must be the final input item. + + - `type: "compaction_trigger"` + + The type of the item. Always `compaction_trigger`. + + - `"compaction_trigger"` - `agent: optional object { agent_name }` @@ -33323,54 +34050,51 @@ the `background` parameter set to `true` can be cancelled. The canonical name of the agent that produced this item. - - `content: optional array of object { text, type }` + - `ItemReference object { id, agent, type }` - Reasoning text content. + An internal identifier for an item to reference. - - `text: string` + - `id: string` - The reasoning text from the model. + The ID of the item to reference. - - `type: "reasoning_text"` + - `agent: optional object { agent_name }` - The type of the reasoning text. Always `reasoning_text`. + The agent that produced this item. - - `"reasoning_text"` + - `agent_name: string` - - `encrypted_content: optional string` + The canonical name of the agent that produced this item. - 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: optional "item_reference"` - - `status: optional "in_progress" or "completed" or "incomplete"` + The type of item to reference. Always `item_reference`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"item_reference"` - - `"in_progress"` + - `Program object { id, call_id, code, 3 more }` - - `"completed"` + - `id: string` - - `"incomplete"` + The unique ID of this program item. - - `Compaction object { encrypted_content, type, id, agent }` + - `call_id: string` - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + The stable call ID of the program item. - - `encrypted_content: string` + - `code: string` - The encrypted content of the compaction summary. + The JavaScript source executed by programmatic tool calling. - - `type: "compaction"` + - `fingerprint: string` - The type of the item. Always `compaction`. + Opaque program replay fingerprint that must be round-tripped. - - `"compaction"` + - `type: "program"` - - `id: optional string` + The item type. Always `program`. - The ID of the compaction item. + - `"program"` - `agent: optional object { agent_name }` @@ -33380,35 +34104,33 @@ the `background` parameter set to `true` can be cancelled. The canonical name of the agent that produced this item. - - `ImageGenerationCall object { id, result, status, 2 more }` - - An image generation request made by the model. + - `ProgramOutput object { id, call_id, result, 3 more }` - `id: string` - The unique ID of the image generation call. + The unique ID of this program output item. - - `result: string` + - `call_id: string` - The generated image encoded in base64. + The call ID of the program item. - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `result: string` - The status of the image generation call. + The result produced by the program item. - - `"in_progress"` + - `status: "completed" or "incomplete"` - - `"completed"` + The terminal status of the program output. - - `"generating"` + - `"completed"` - - `"failed"` + - `"incomplete"` - - `type: "image_generation_call"` + - `type: "program_output"` - The type of the image generation call. Always `image_generation_call`. + The item type. Always `program_output`. - - `"image_generation_call"` + - `"program_output"` - `agent: optional object { agent_name }` @@ -33418,1974 +34140,2112 @@ the `background` parameter set to `true` can be cancelled. The canonical name of the agent that produced this item. - - `CodeInterpreterCall object { id, code, container_id, 4 more }` +- `instructions: optional string` - A tool call to run code. + A system (or developer) message inserted into the model's context. - - `id: string` + 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. - The unique ID of the code interpreter tool call. +- `max_output_tokens: optional number` - - `code: 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 code to run, or null if not available. +- `max_tool_calls: optional number` - - `container_id: string` + 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 ID of the container used to run the code. +- `metadata: optional map[string]` - - `outputs: array of object { logs, type } or object { type, url }` + 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 outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `Logs object { logs, type }` +- `model: optional "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - The logs output from the code interpreter. + 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. - - `logs: string` + - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` - The logs output from the code interpreter. + 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: "logs"` + - `"gpt-5.6-sol"` - The type of the output. Always `logs`. + - `"gpt-5.6-terra"` - - `"logs"` + - `"gpt-5.6-luna"` - - `Image object { type, url }` + - `"gpt-5.4"` - The image output from the code interpreter. + - `"gpt-5.4-mini"` - - `type: "image"` + - `"gpt-5.4-nano"` - The type of the output. Always `image`. + - `"gpt-5.4-mini-2026-03-17"` - - `"image"` + - `"gpt-5.4-nano-2026-03-17"` - - `url: string` + - `"gpt-5.3-chat-latest"` - The URL of the image output from the code interpreter. + - `"gpt-5.2"` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `"gpt-5.2-2025-12-11"` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `"gpt-5.2-chat-latest"` - - `"in_progress"` + - `"gpt-5.2-pro"` - - `"completed"` + - `"gpt-5.2-pro-2025-12-11"` - - `"incomplete"` + - `"gpt-5.1"` - - `"interpreting"` + - `"gpt-5.1-2025-11-13"` - - `"failed"` + - `"gpt-5.1-codex"` - - `type: "code_interpreter_call"` + - `"gpt-5.1-mini"` - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `"gpt-5.1-chat-latest"` - - `"code_interpreter_call"` + - `"gpt-5"` - - `agent: optional object { agent_name }` + - `"gpt-5-mini"` - The agent that produced this item. + - `"gpt-5-nano"` - - `agent_name: string` + - `"gpt-5-2025-08-07"` - The canonical name of the agent that produced this item. + - `"gpt-5-mini-2025-08-07"` - - `LocalShellCall object { id, action, call_id, 3 more }` + - `"gpt-5-nano-2025-08-07"` - A tool call to run a command on the local shell. + - `"gpt-5-chat-latest"` - - `id: string` + - `"gpt-4.1"` - The unique ID of the local shell call. + - `"gpt-4.1-mini"` - - `action: object { command, env, type, 3 more }` + - `"gpt-4.1-nano"` - Execute a shell command on the server. + - `"gpt-4.1-2025-04-14"` - - `command: array of string` + - `"gpt-4.1-mini-2025-04-14"` - The command to run. + - `"gpt-4.1-nano-2025-04-14"` - - `env: map[string]` + - `"o4-mini"` - Environment variables to set for the command. + - `"o4-mini-2025-04-16"` - - `type: "exec"` + - `"o3"` - The type of the local shell action. Always `exec`. + - `"o3-2025-04-16"` - - `"exec"` + - `"o3-mini"` - - `timeout_ms: optional number` + - `"o3-mini-2025-01-31"` - Optional timeout in milliseconds for the command. + - `"o1"` - - `user: optional string` + - `"o1-2024-12-17"` - Optional user to run the command as. + - `"o1-preview"` - - `working_directory: optional string` + - `"o1-preview-2024-09-12"` - Optional working directory to run the command in. + - `"o1-mini"` - - `call_id: string` + - `"o1-mini-2024-09-12"` - The unique ID of the local shell tool call generated by the model. + - `"gpt-4o"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"gpt-4o-2024-11-20"` - The status of the local shell call. + - `"gpt-4o-2024-08-06"` - - `"in_progress"` + - `"gpt-4o-2024-05-13"` - - `"completed"` + - `"gpt-4o-audio-preview"` - - `"incomplete"` + - `"gpt-4o-audio-preview-2024-10-01"` - - `type: "local_shell_call"` + - `"gpt-4o-audio-preview-2024-12-17"` - The type of the local shell call. Always `local_shell_call`. + - `"gpt-4o-audio-preview-2025-06-03"` - - `"local_shell_call"` + - `"gpt-4o-mini-audio-preview"` - - `agent: optional object { agent_name }` + - `"gpt-4o-mini-audio-preview-2024-12-17"` - The agent that produced this item. + - `"gpt-4o-search-preview"` - - `agent_name: string` + - `"gpt-4o-mini-search-preview"` - The canonical name of the agent that produced this item. + - `"gpt-4o-search-preview-2025-03-11"` - - `LocalShellCallOutput object { id, output, type, 2 more }` + - `"gpt-4o-mini-search-preview-2025-03-11"` - The output of a local shell tool call. + - `"chatgpt-4o-latest"` - - `id: string` + - `"codex-mini-latest"` - The unique ID of the local shell tool call generated by the model. + - `"gpt-4o-mini"` - - `output: string` + - `"gpt-4o-mini-2024-07-18"` - A JSON string of the output of the local shell tool call. + - `"gpt-4-turbo"` - - `type: "local_shell_call_output"` + - `"gpt-4-turbo-2024-04-09"` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `"gpt-4-0125-preview"` - - `"local_shell_call_output"` + - `"gpt-4-turbo-preview"` - - `agent: optional object { agent_name }` + - `"gpt-4-1106-preview"` - The agent that produced this item. + - `"gpt-4-vision-preview"` - - `agent_name: string` + - `"gpt-4"` - The canonical name of the agent that produced this item. + - `"gpt-4-0314"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"gpt-4-0613"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `"gpt-4-32k"` - - `"in_progress"` + - `"gpt-4-32k-0314"` - - `"completed"` + - `"gpt-4-32k-0613"` - - `"incomplete"` + - `"gpt-3.5-turbo"` - - `ShellCall object { action, call_id, type, 5 more }` + - `"gpt-3.5-turbo-16k"` - A tool representing a request to execute one or more shell commands. + - `"gpt-3.5-turbo-0301"` - - `action: object { commands, max_output_length, timeout_ms }` + - `"gpt-3.5-turbo-0613"` - The shell commands and limits that describe how to run the tool call. + - `"gpt-3.5-turbo-1106"` - - `commands: array of string` + - `"gpt-3.5-turbo-0125"` - Ordered shell commands for the execution environment to run. + - `"gpt-3.5-turbo-16k-0613"` - - `max_output_length: optional number` + - `"o1-pro"` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `"o1-pro-2025-03-19"` - - `timeout_ms: optional number` + - `"o3-pro"` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `"o3-pro-2025-06-10"` - - `call_id: string` + - `"o3-deep-research"` - The unique ID of the shell tool call generated by the model. + - `"o3-deep-research-2025-06-26"` - - `type: "shell_call"` + - `"o4-mini-deep-research"` - The type of the item. Always `shell_call`. + - `"o4-mini-deep-research-2025-06-26"` - - `"shell_call"` + - `"computer-use-preview"` - - `id: optional string` + - `"computer-use-preview-2025-03-11"` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `"gpt-5-codex"` - - `agent: optional object { agent_name }` + - `"gpt-5-pro"` - The agent that produced this item. + - `"gpt-5-pro-2025-10-06"` - - `agent_name: string` + - `"gpt-5.1-codex-max"` - The canonical name of the agent that produced this item. + - `string` - - `caller: optional object { type } or object { caller_id, type }` +- `moderation: optional object { model, policy }` - The execution context that produced this tool call. + Configuration for running moderation on the input and output of this response. - - `Direct object { type }` + - `model: string` - - `type: "direct"` + The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'. - The caller type. Always `direct`. + - `policy: optional object { input, output }` - - `"direct"` + The policy to apply to moderated response input and output. - - `Program object { caller_id, type }` + - `input: optional object { mode }` - - `caller_id: string` + The moderation policy for the response input. - The call ID of the program item that produced this tool call. + - `mode: "score" or "block"` - - `type: "program"` + - `"score"` - The caller type. Always `program`. + - `"block"` - - `"program"` + - `output: optional object { mode }` - - `environment: optional BetaLocalEnvironment or BetaContainerReference` + The moderation policy for the response output. - The environment to execute the shell commands in. + - `mode: "score" or "block"` - - `BetaLocalEnvironment object { type, skills }` + - `"score"` - - `BetaContainerReference object { container_id, type }` + - `"block"` - - `status: optional "in_progress" or "completed" or "incomplete"` +- `multi_agent: optional object { enabled, max_concurrent_subagents }` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + Configuration for server-hosted multi-agent execution. - - `"in_progress"` + - `enabled: boolean` - - `"completed"` + Whether to enable server-hosted multi-agent execution for this response. - - `"incomplete"` + - `max_concurrent_subagents: optional number` - - `ShellCallOutput object { call_id, output, type, 5 more }` + `max_concurrent_subagents` sets the maximum number of subagents that can be active simultaneously across the entire agent tree. It includes all descendants—children, grandchildren, and deeper subagents—but excludes the root agent. + The API does not impose a fixed upper bound on this setting. The default is `3`, which is recommended for most workloads. Multi-agent runs also have no fixed limit on tree depth or the total number of subagents created during a run. - The streamed output items emitted by a shell tool call. +- `parallel_tool_calls: optional boolean` - - `call_id: string` + Whether to allow the model to run tool calls in parallel. - The unique ID of the shell tool call generated by the model. +- `previous_response_id: optional string` - - `output: array of BetaResponseFunctionShellCallOutputContent` + 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`. - Captured chunks of stdout and stderr output, along with their associated outcomes. +- `prompt: optional BetaResponsePrompt` - - `outcome: object { type } or object { exit_code, type }` + Reference to a prompt template and its variables. + [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). - The exit or timeout outcome associated with this shell call. + - `id: string` - - `Timeout object { type }` + The unique identifier of the prompt template to use. - Indicates that the shell call exceeded its configured time limit. + - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` - - `type: "timeout"` + 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 outcome type. Always `timeout`. + - `string` - - `"timeout"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `Exit object { exit_code, type }` + A text input to the model. - Indicates that the shell commands finished and returned an exit code. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `exit_code: number` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - The exit code returned by the shell process. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `type: "exit"` + A file input to the model. - The outcome type. Always `exit`. + - `version: optional string` - - `"exit"` + Optional version of the prompt template. - - `stderr: string` +- `prompt_cache_key: optional string` - Captured stderr output for the shell 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). - - `stdout: string` +- `prompt_cache_options: optional object { mode, ttl }` - Captured stdout output for the shell call. + 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. - - `type: "shell_call_output"` + - `mode: optional "implicit" or "explicit"` - The type of the item. Always `shell_call_output`. + 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. - - `"shell_call_output"` + - `"implicit"` - - `id: optional string` + - `"explicit"` - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `ttl: optional "30m"` - - `agent: optional object { agent_name }` + 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 agent that produced this item. + - `"30m"` - - `agent_name: string` +- `prompt_cache_retention: optional "in_memory" or "24h"` - The canonical name of the agent that produced this item. + Deprecated. Use `prompt_cache_options.ttl` instead. - - `caller: optional object { type } or object { caller_id, 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. - The execution context that produced this tool call. + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `Direct object { type }` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `type: "direct"` + - `"in_memory"` - The caller type. Always `direct`. + - `"24h"` - - `"direct"` +- `reasoning: optional object { context, effort, generate_summary, 2 more }` - - `Program object { caller_id, type }` + **gpt-5 and o-series models only** - - `caller_id: string` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - The call ID of the program item that produced this tool call. + - `context: optional "auto" or "current_turn" or "all_turns"` - - `type: "program"` + 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`. - The caller type. Always `program`. + When returned on a response, this is the effective reasoning context mode + used for the response. - - `"program"` + - `"auto"` - - `max_output_length: optional number` + - `"current_turn"` - The maximum number of UTF-8 characters captured for this shell call's combined output. + - `"all_turns"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `effort: optional "none" or "minimal" or "low" or 4 more` - The status of the shell call output. + 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. - - `"in_progress"` + - `"none"` - - `"completed"` + - `"minimal"` - - `"incomplete"` + - `"low"` - - `ApplyPatchCall object { call_id, operation, status, 4 more }` + - `"medium"` - A tool call representing a request to create, delete, or update files using diff patches. + - `"high"` - - `call_id: string` + - `"xhigh"` - The unique ID of the apply patch tool call generated by the model. + - `"max"` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `generate_summary: optional "auto" or "concise" or "detailed"` - The specific create, delete, or update instruction for the apply_patch tool call. + **Deprecated:** use `summary` instead. - - `CreateFile object { diff, path, type }` + 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`. - Instruction for creating a new file via the apply_patch tool. + - `"auto"` - - `diff: string` + - `"concise"` - Unified diff content to apply when creating the file. + - `"detailed"` - - `path: string` + - `mode: optional string or "standard" or "pro"` - Path of the file to create relative to the workspace root. + Controls the reasoning execution mode for the request. - - `type: "create_file"` + When returned on a response, this is the effective execution mode. - The operation type. Always `create_file`. + - `string` - - `"create_file"` + - `"standard" or "pro"` - - `DeleteFile object { path, type }` + Controls the reasoning execution mode for the request. - Instruction for deleting an existing file via the apply_patch tool. + When returned on a response, this is the effective execution mode. - - `path: string` + - `"standard"` - Path of the file to delete relative to the workspace root. + - `"pro"` - - `type: "delete_file"` + - `summary: optional "auto" or "concise" or "detailed"` - The operation type. Always `delete_file`. + 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`. - - `"delete_file"` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `UpdateFile object { diff, path, type }` + - `"auto"` - Instruction for updating an existing file via the apply_patch tool. + - `"concise"` - - `diff: string` + - `"detailed"` - Unified diff content to apply to the existing file. +- `safety_identifier: optional string` - - `path: 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). - Path of the file to update relative to the workspace root. +- `service_tier: optional "auto" or "default" or "flex" or 2 more` - - `type: "update_file"` + Specifies the processing type used for serving the request. - The operation type. Always `update_file`. + - 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'. - - `"update_file"` + 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. - - `status: "in_progress" or "completed"` + - `"auto"` - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `"default"` - - `"in_progress"` + - `"flex"` - - `"completed"` + - `"scale"` - - `type: "apply_patch_call"` + - `"priority"` - The type of the item. Always `apply_patch_call`. +- `store: optional boolean` - - `"apply_patch_call"` + Whether to store the generated model response for later retrieval via + API. - - `id: optional string` +- `stream: optional boolean` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + 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. - - `agent: optional object { agent_name }` +- `stream_options: optional object { include_obfuscation }` - The agent that produced this item. + Options for streaming responses. Only set this when you set `stream: true`. - - `agent_name: string` + - `include_obfuscation: optional boolean` - The canonical name of the agent that produced this item. + 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. - - `caller: optional object { type } or object { caller_id, type }` +- `temperature: optional number` - The execution context that produced this 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. - - `Direct object { type }` +- `text: optional BetaResponseTextConfig` - - `type: "direct"` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - The caller type. Always `direct`. + - [Text inputs and outputs](/docs/guides/text) + - [Structured Outputs](/docs/guides/structured-outputs) - - `"direct"` + - `format: optional BetaResponseFormatTextConfig` - - `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:** - The caller type. Always `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. - - `"program"` + - `Text object { type }` - - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` + Default response format. Used to generate text responses. - The streamed output emitted by an apply patch tool call. + - `type: "text"` - - `call_id: string` + The type of response format being defined. Always `text`. - The unique ID of the apply patch tool call generated by the model. + - `"text"` - - `status: "completed" or "failed"` + - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` - The status of the apply patch tool call output. One of `completed` or `failed`. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `"completed"` + - `name: string` - - `"failed"` + 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: "apply_patch_call_output"` + - `schema: map[unknown]` - The type of the item. Always `apply_patch_call_output`. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `"apply_patch_call_output"` + - `type: "json_schema"` - - `id: optional string` + The type of response format being defined. Always `json_schema`. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `"json_schema"` - - `agent: optional object { agent_name }` + - `description: optional string` - The agent that produced this item. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `agent_name: string` + - `strict: optional boolean` - The canonical name of the agent that produced this item. + 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). - - `caller: optional object { type } or object { caller_id, type }` + - `JSONObject object { type }` - The execution context that produced this tool call. + 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. - - `Direct object { type }` + - `type: "json_object"` - - `type: "direct"` + The type of response format being defined. Always `json_object`. - The caller type. Always `direct`. + - `"json_object"` - - `"direct"` + - `verbosity: optional "low" or "medium" or "high"` - - `Program 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`. - - `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`. +- `tool_choice: optional BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - - `"program"` + 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. - - `output: optional string` + - `BetaToolChoiceOptions = "none" or "auto" or "required"` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + Controls which (if any) tool is called by the model. - - `McpListTools object { id, server_label, tools, 3 more }` + `none` means the model will not call any tool and instead generates a message. - A list of tools available on an MCP server. + `auto` means the model can pick between generating a message or calling one or + more tools. - - `id: string` + `required` means the model must call one or more tools. - The unique ID of the list. + - `"none"` - - `server_label: string` + - `"auto"` - The label of the MCP server. + - `"required"` - - `tools: array of object { input_schema, name, annotations, description }` + - `BetaToolChoiceAllowed object { mode, tools, type }` - The tools available on the server. + Constrains the tools available to the model to a pre-defined set. - - `input_schema: unknown` + - `mode: "auto" or "required"` - The JSON schema describing the tool's input. + Constrains the tools available to the model to a pre-defined set. - - `name: string` + `auto` allows the model to pick from among the allowed tools and generate a + message. - The name of the tool. + `required` requires the model to call one or more of the allowed tools. - - `annotations: optional unknown` + - `"auto"` - Additional annotations about the tool. + - `"required"` - - `description: optional string` + - `tools: array of map[unknown]` - The description of the tool. + A list of tool definitions that the model should be allowed to call. - - `type: "mcp_list_tools"` + For the Responses API, the list of tool definitions might look like: - The type of the item. Always `mcp_list_tools`. + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `"mcp_list_tools"` + - `type: "allowed_tools"` - - `agent: optional object { agent_name }` + Allowed tool configuration type. Always `allowed_tools`. - The agent that produced this item. + - `"allowed_tools"` - - `agent_name: string` + - `BetaToolChoiceTypes object { type }` - The canonical name of the agent that produced this item. + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](/docs/guides/tools). - - `error: optional string` + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` - Error message if the server could not list tools. + The type of hosted tool the model should to use. Learn more about + [built-in tools](/docs/guides/tools). - - `McpApprovalRequest object { id, arguments, name, 3 more }` + Allowed values are: - A request for human approval of a tool invocation. + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `id: string` + - `"file_search"` - The unique ID of the approval request. + - `"web_search_preview"` - - `arguments: string` + - `"computer"` - A JSON string of arguments for the tool. + - `"computer_use_preview"` - - `name: string` + - `"computer_use"` - The name of the tool to run. + - `"web_search_preview_2025_03_11"` - - `server_label: string` + - `"image_generation"` - The label of the MCP server making the request. + - `"code_interpreter"` - - `type: "mcp_approval_request"` + - `BetaToolChoiceFunction object { name, type }` - The type of the item. Always `mcp_approval_request`. + Use this option to force the model to call a specific function. - - `"mcp_approval_request"` + - `name: string` - - `agent: optional object { agent_name }` + The name of the function to call. - The agent that produced this item. + - `type: "function"` - - `agent_name: string` + For function calling, the type is always `function`. - The canonical name of the agent that produced this item. + - `"function"` - - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` + - `BetaToolChoiceMcp object { server_label, type, name }` - A response to an MCP approval request. + Use this option to force the model to call a specific tool on a remote MCP server. - - `approval_request_id: string` + - `server_label: string` - The ID of the approval request being answered. + The label of the MCP server to use. - - `approve: boolean` + - `type: "mcp"` - Whether the request was approved. + For MCP tools, the type is always `mcp`. - - `type: "mcp_approval_response"` + - `"mcp"` - The type of the item. Always `mcp_approval_response`. + - `name: optional string` - - `"mcp_approval_response"` + The name of the tool to call on the server. - - `id: optional string` + - `BetaToolChoiceCustom object { name, type }` - The unique ID of the approval response + Use this option to force the model to call a specific custom tool. - - `agent: optional object { agent_name }` + - `name: string` - The agent that produced this item. + The name of the custom tool to call. - - `agent_name: string` + - `type: "custom"` - The canonical name of the agent that produced this item. + For custom tool calling, the type is always `custom`. - - `reason: optional string` + - `"custom"` - Optional reason for the decision. + - `BetaSpecificProgrammaticToolCallingParam object { type }` - - `McpCall object { id, arguments, name, 7 more }` + - `type: "programmatic_tool_calling"` - An invocation of a tool on an MCP server. + The tool to call. Always `programmatic_tool_calling`. - - `id: string` + - `"programmatic_tool_calling"` - The unique ID of the tool call. + - `BetaToolChoiceApplyPatch object { type }` - - `arguments: string` + Forces the model to call the apply_patch tool when executing a tool call. - A JSON string of the arguments passed to the tool. + - `type: "apply_patch"` - - `name: string` + The tool to call. Always `apply_patch`. - The name of the tool that was run. + - `"apply_patch"` - - `server_label: string` + - `BetaToolChoiceShell object { type }` - The label of the MCP server running the tool. + Forces the model to call the shell tool when a tool call is required. - - `type: "mcp_call"` + - `type: "shell"` - The type of the item. Always `mcp_call`. + The tool to call. Always `shell`. - - `"mcp_call"` + - `"shell"` - - `agent: optional object { agent_name }` +- `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` - The agent that produced this item. + 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. - - `agent_name: string` + We support the following categories of tools: - The canonical name of the agent that produced this item. + - **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. - - `approval_request_id: optional string` + - `Function object { name, parameters, strict, 5 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. + 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). - - `error: optional string` + - `name: string` - The error from the tool call, if any. + The name of the function to call. - - `output: optional string` + - `parameters: map[unknown]` - The output from the tool call. + A JSON schema object describing the parameters of the function. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `strict: boolean` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + Whether strict parameter validation is enforced for this function tool. - - `"in_progress"` + - `type: "function"` - - `"completed"` + The type of the function tool. Always `function`. - - `"incomplete"` + - `"function"` - - `"calling"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"failed"` + The tool invocation context(s). - - `CustomToolCallOutput object { call_id, output, type, 3 more }` + - `"direct"` - The output of a custom tool call from your code, being sent back to the model. + - `"programmatic"` - - `call_id: string` + - `defer_loading: optional boolean` - The call ID, used to map this custom tool call output to a custom tool call. + Whether this function is deferred and loaded via tool search. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `description: optional string` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + A description of the function. Used by the model to determine whether or not to call the function. - - `StringOutput = string` + - `output_schema: optional map[unknown]` - A string of the output of the custom tool call. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - Text, image, or file output of the custom tool call. + 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). - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `type: "file_search"` - A text input to the model. + The type of the file search tool. Always `file_search`. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `"file_search"` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `vector_store_ids: array of string` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + The IDs of the vector stores to search. - A file input to the model. + - `filters: optional object { key, type, value } or object { filters, type }` - - `type: "custom_tool_call_output"` + A filter to apply. - The type of the custom tool call output. Always `custom_tool_call_output`. + - `ComparisonFilter object { key, type, value }` - - `"custom_tool_call_output"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `id: optional string` + - `key: string` - The unique ID of the custom tool call output in the OpenAI platform. + The key to compare against the value. - - `agent: optional object { agent_name }` + - `type: "eq" or "ne" or "gt" or 5 more` - The agent that produced this item. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `agent_name: string` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - The canonical name of the agent that produced this item. + - `"eq"` - - `caller: optional object { type } or object { caller_id, type }` + - `"ne"` - The execution context that produced this tool call. + - `"gt"` - - `Direct object { type }` + - `"gte"` - - `type: "direct"` + - `"lt"` - The caller type. Always `direct`. + - `"lte"` - - `"direct"` + - `"in"` - - `Program object { caller_id, type }` + - `"nin"` - - `caller_id: string` + - `value: string or number or boolean or array of string or number` - The call ID of the program item that produced this tool call. + The value to compare against the attribute key; supports string, number, or boolean types. - - `type: "program"` + - `string` - The caller type. Always `program`. + - `number` - - `"program"` + - `boolean` - - `CustomToolCall object { call_id, input, name, 5 more }` + - `array of string or number` - A call to a custom tool created by the model. + - `string` - - `call_id: string` + - `number` - An identifier used to map this custom tool call to a tool call output. + - `CompoundFilter object { filters, type }` - - `input: string` + Combine multiple filters using `and` or `or`. - The input for the custom tool call generated by the model. + - `filters: array of object { key, type, value } or unknown` - - `name: string` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The name of the custom tool being called. + - `ComparisonFilter object { key, type, value }` - - `type: "custom_tool_call"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The type of the custom tool call. Always `custom_tool_call`. + - `key: string` - - `"custom_tool_call"` + The key to compare against the value. - - `id: optional string` + - `type: "eq" or "ne" or "gt" or 5 more` - The unique ID of the custom tool call in the OpenAI platform. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `agent: optional object { agent_name }` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - The agent that produced this item. + - `"eq"` - - `agent_name: string` + - `"ne"` - The canonical name of the agent that produced this item. + - `"gt"` - - `caller: optional object { type } or object { caller_id, type }` + - `"gte"` - The execution context that produced this tool call. + - `"lt"` - - `Direct object { type }` + - `"lte"` - - `type: "direct"` + - `"in"` - - `"direct"` + - `"nin"` - - `Program object { caller_id, type }` + - `value: string or number or boolean or array of string or number` - - `caller_id: string` + The value to compare against the attribute key; supports string, number, or boolean types. - The call ID of the program item that produced this tool call. + - `string` - - `type: "program"` + - `number` - - `"program"` + - `boolean` - - `namespace: optional string` + - `array of string or number` - The namespace of the custom tool being called. + - `string` - - `CompactionTrigger object { type, agent }` + - `number` - Compacts the current context. Must be the final input item. + - `unknown` - - `type: "compaction_trigger"` + - `type: "and" or "or"` - The type of the item. Always `compaction_trigger`. + Type of operation: `and` or `or`. - - `"compaction_trigger"` + - `"and"` - - `agent: optional object { agent_name }` + - `"or"` - The agent that produced this item. + - `max_num_results: optional number` - - `agent_name: string` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - The canonical name of the agent that produced this item. + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `ItemReference object { id, agent, type }` + Ranking options for search. - An internal identifier for an item to reference. + - `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 ID of the item to reference. + - `embedding_weight: number` - - `agent: optional object { agent_name }` + The weight of the embedding in the reciprocal ranking fusion. - The agent that produced this item. + - `text_weight: number` - - `agent_name: string` + The weight of the text in the reciprocal ranking fusion. - The canonical name of the agent that produced this item. + - `ranker: optional "auto" or "default-2024-11-15"` - - `type: optional "item_reference"` + The ranker to use for the file search. - The type of item to reference. Always `item_reference`. + - `"auto"` - - `"item_reference"` + - `"default-2024-11-15"` - - `Program object { id, call_id, code, 3 more }` + - `score_threshold: optional number` - - `id: string` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - The unique ID of this program item. + - `Computer object { type }` - - `call_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 stable call ID of the program item. + - `type: "computer"` - - `code: string` + The type of the computer tool. Always `computer`. - The JavaScript source executed by programmatic tool calling. + - `"computer"` - - `fingerprint: string` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - Opaque program replay fingerprint that must be round-tripped. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `type: "program"` + - `display_height: number` - The item type. Always `program`. + The height of the computer display. - - `"program"` + - `display_width: number` - - `agent: optional object { agent_name }` + The width of the computer display. - The agent that produced this item. + - `environment: "windows" or "mac" or "linux" or 2 more` - - `agent_name: string` + The type of computer environment to control. - The canonical name of the agent that produced this item. + - `"windows"` - - `ProgramOutput object { id, call_id, result, 3 more }` + - `"mac"` - - `id: string` + - `"linux"` - The unique ID of this program output item. + - `"ubuntu"` - - `call_id: string` + - `"browser"` - The call ID of the program item. + - `type: "computer_use_preview"` - - `result: string` + The type of the computer use tool. Always `computer_use_preview`. - The result produced by the program item. + - `"computer_use_preview"` - - `status: "completed" or "incomplete"` + - `WebSearch object { type, filters, search_context_size, user_location }` - The terminal status of the program output. + 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`. - - `type: "program_output"` + - `"web_search"` - The item type. Always `program_output`. + - `"web_search_2025_08_26"` - - `"program_output"` + - `filters: optional object { allowed_domains }` - - `agent: optional object { agent_name }` + Filters for the search. - The agent that produced this item. + - `allowed_domains: optional array of string` - - `agent_name: string` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - The canonical name of the agent that produced this item. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `metadata: map[string]` + - `search_context_size: optional "low" or "medium" or "high"` - 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. + 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. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"low"` - - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + - `"medium"` - 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. + - `"high"` - - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` + - `user_location: optional object { city, country, region, 2 more }` - 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. + The approximate location of the user. - - `"gpt-5.6-sol"` + - `city: optional string` - - `"gpt-5.6-terra"` + Free text input for the city of the user, e.g. `San Francisco`. - - `"gpt-5.6-luna"` + - `country: optional string` - - `"gpt-5.4"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"gpt-5.4-mini"` + - `region: optional string` - - `"gpt-5.4-nano"` + Free text input for the region of the user, e.g. `California`. - - `"gpt-5.4-mini-2026-03-17"` + - `timezone: optional string` - - `"gpt-5.4-nano-2026-03-17"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"gpt-5.3-chat-latest"` + - `type: optional "approximate"` - - `"gpt-5.2"` + The type of location approximation. Always `approximate`. - - `"gpt-5.2-2025-12-11"` + - `"approximate"` - - `"gpt-5.2-chat-latest"` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `"gpt-5.2-pro"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `"gpt-5.2-pro-2025-12-11"` + - `server_label: string` - - `"gpt-5.1"` + A label for this MCP server, used to identify it in tool calls. - - `"gpt-5.1-2025-11-13"` + - `type: "mcp"` - - `"gpt-5.1-codex"` + The type of the MCP tool. Always `mcp`. - - `"gpt-5.1-mini"` + - `"mcp"` - - `"gpt-5.1-chat-latest"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"gpt-5"` + The tool invocation context(s). - - `"gpt-5-mini"` + - `"direct"` - - `"gpt-5-nano"` + - `"programmatic"` - - `"gpt-5-2025-08-07"` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `"gpt-5-mini-2025-08-07"` + List of allowed tool names or a filter object. - - `"gpt-5-nano-2025-08-07"` + - `McpAllowedTools = array of string` - - `"gpt-5-chat-latest"` + A string array of allowed tool names - - `"gpt-4.1"` + - `McpToolFilter object { read_only, tool_names }` - - `"gpt-4.1-mini"` + A filter object to specify which tools are allowed. - - `"gpt-4.1-nano"` + - `read_only: optional boolean` - - `"gpt-4.1-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. - - `"gpt-4.1-mini-2025-04-14"` + - `tool_names: optional array of string` - - `"gpt-4.1-nano-2025-04-14"` + List of allowed tool names. - - `"o4-mini"` + - `authorization: optional string` - - `"o4-mini-2025-04-16"` + 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. - - `"o3"` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `"o3-2025-04-16"` + 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). - - `"o3-mini"` + Currently supported `connector_id` values are: - - `"o3-mini-2025-01-31"` + - 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` - - `"o1"` + - `"connector_dropbox"` - - `"o1-2024-12-17"` + - `"connector_gmail"` - - `"o1-preview"` + - `"connector_googlecalendar"` - - `"o1-preview-2024-09-12"` + - `"connector_googledrive"` - - `"o1-mini"` + - `"connector_microsoftteams"` - - `"o1-mini-2024-09-12"` + - `"connector_outlookcalendar"` - - `"gpt-4o"` + - `"connector_outlookemail"` - - `"gpt-4o-2024-11-20"` + - `"connector_sharepoint"` - - `"gpt-4o-2024-08-06"` + - `defer_loading: optional boolean` - - `"gpt-4o-2024-05-13"` + Whether this MCP tool is deferred and discovered via tool search. - - `"gpt-4o-audio-preview"` + - `headers: optional map[string]` - - `"gpt-4o-audio-preview-2024-10-01"` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `"gpt-4o-audio-preview-2024-12-17"` + - `require_approval: optional object { always, never } or "always" or "never"` - - `"gpt-4o-audio-preview-2025-06-03"` + Specify which of the MCP server's tools require approval. - - `"gpt-4o-mini-audio-preview"` + - `McpToolApprovalFilter object { always, never }` - - `"gpt-4o-mini-audio-preview-2024-12-17"` + 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-4o-search-preview"` + - `always: optional object { read_only, tool_names }` - - `"gpt-4o-mini-search-preview"` + A filter object to specify which tools are allowed. - - `"gpt-4o-search-preview-2025-03-11"` + - `read_only: optional boolean` - - `"gpt-4o-mini-search-preview-2025-03-11"` + 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. - - `"chatgpt-4o-latest"` + - `tool_names: optional array of string` - - `"codex-mini-latest"` + List of allowed tool names. - - `"gpt-4o-mini"` + - `never: optional object { read_only, tool_names }` - - `"gpt-4o-mini-2024-07-18"` + A filter object to specify which tools are allowed. - - `"gpt-4-turbo"` + - `read_only: optional boolean` - - `"gpt-4-turbo-2024-04-09"` + 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-0125-preview"` + - `tool_names: optional array of string` - - `"gpt-4-turbo-preview"` + List of allowed tool names. - - `"gpt-4-1106-preview"` + - `McpToolApprovalSetting = "always" or "never"` - - `"gpt-4-vision-preview"` + 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. - - `"gpt-4"` + - `"always"` - - `"gpt-4-0314"` + - `"never"` - - `"gpt-4-0613"` + - `server_description: optional string` - - `"gpt-4-32k"` + Optional description of the MCP server, used to provide more context. - - `"gpt-4-32k-0314"` + - `server_url: optional string` - - `"gpt-4-32k-0613"` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `"gpt-3.5-turbo"` + - `tunnel_id: optional string` - - `"gpt-3.5-turbo-16k"` + 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-3.5-turbo-0301"` + - `CodeInterpreter object { container, type, allowed_callers }` - - `"gpt-3.5-turbo-0613"` + A tool that runs Python code to help generate a response to a prompt. - - `"gpt-3.5-turbo-1106"` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `"gpt-3.5-turbo-0125"` + 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-3.5-turbo-16k-0613"` + - `string` - - `"o1-pro"` + The container ID. - - `"o1-pro-2025-03-19"` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `"o3-pro"` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `"o3-pro-2025-06-10"` + - `type: "auto"` - - `"o3-deep-research"` + Always `auto`. - - `"o3-deep-research-2025-06-26"` + - `"auto"` - - `"o4-mini-deep-research"` + - `file_ids: optional array of string` - - `"o4-mini-deep-research-2025-06-26"` + An optional list of uploaded files to make available to your code. - - `"computer-use-preview"` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `"computer-use-preview-2025-03-11"` + The memory limit for the code interpreter container. - - `"gpt-5-codex"` + - `"1g"` - - `"gpt-5-pro"` + - `"4g"` - - `"gpt-5-pro-2025-10-06"` + - `"16g"` - - `"gpt-5.1-codex-max"` + - `"64g"` - - `string` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `object: "response"` + Network access policy for the container. - The object type of this resource - always set to `response`. + - `BetaContainerNetworkPolicyDisabled object { type }` - - `"response"` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `output: array of BetaResponseOutputItem` + - `type: "code_interpreter"` - An array of content items generated by the model. + The type of the code interpreter tool. Always `code_interpreter`. - - 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. + - `"code_interpreter"` - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + - `allowed_callers: optional array of "direct" or "programmatic"` - An output message from the model. + The tool invocation context(s). - - `FileSearchCall object { id, queries, status, 3 more }` + - `"direct"` - The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + - `"programmatic"` - - `id: string` + - `ProgrammaticToolCalling object { type }` - The unique ID of the file search tool call. + - `type: "programmatic_tool_calling"` - - `queries: array of string` + The type of the tool. Always `programmatic_tool_calling`. - The queries used to search for files. + - `"programmatic_tool_calling"` - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `ImageGeneration object { type, action, background, 9 more }` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + A tool that generates images using the GPT image models. - - `"in_progress"` + - `type: "image_generation"` - - `"searching"` + The type of the image generation tool. Always `image_generation`. - - `"completed"` + - `"image_generation"` - - `"incomplete"` + - `action: optional "generate" or "edit" or "auto"` - - `"failed"` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `type: "file_search_call"` + - `"generate"` - The type of the file search tool call. Always `file_search_call`. + - `"edit"` - - `"file_search_call"` + - `"auto"` - - `agent: optional object { agent_name }` + - `background: optional "transparent" or "opaque" or "auto"` - The agent that produced this item. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `agent_name: string` + - `"transparent"` - The canonical name of the agent that produced this item. + - `"opaque"` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `"auto"` - The results of the file search tool call. + - `input_fidelity: optional "high" or "low"` - - `attributes: optional map[string or number or boolean]` + 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`. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + - `"high"` - - `string` + - `"low"` - - `number` + - `input_image_mask: optional object { file_id, image_url }` - - `boolean` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - `file_id: optional string` - The unique ID of the file. + File ID for the mask image. - - `filename: optional string` + - `image_url: optional string` - The name of the file. + Base64-encoded mask image. - - `score: optional number` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The relevance score of the file - a value between 0 and 1. + The image generation model to use. Default: `gpt-image-1`. - - `text: optional string` + - `string` - The text that was retrieved from the file. + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `FunctionCall object { arguments, call_id, name, 6 more }` + The image generation model to use. Default: `gpt-image-1`. - A tool call to run a function. See the - [function calling guide](/docs/guides/function-calling) for more information. + - `"gpt-image-1"` - - `arguments: string` + - `"gpt-image-1-mini"` - A JSON string of the arguments to pass to the function. + - `"gpt-image-1.5"` - - `call_id: string` + - `moderation: optional "auto" or "low"` - The unique ID of the function tool call generated by the model. + Moderation level for the generated image. Default: `auto`. - - `name: string` + - `"auto"` - The name of the function to run. + - `"low"` - - `type: "function_call"` + - `output_compression: optional number` - The type of the function tool call. Always `function_call`. + Compression level for the output image. Default: 100. - - `"function_call"` + - `output_format: optional "png" or "webp" or "jpeg"` - - `id: optional string` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The unique ID of the function tool call. + - `"png"` - - `agent: optional object { agent_name }` + - `"webp"` - The agent that produced this item. + - `"jpeg"` - - `agent_name: string` + - `partial_images: optional number` - The canonical name of the agent that produced this item. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `caller: optional object { type } or object { caller_id, type }` + - `quality: optional "low" or "medium" or "high" or "auto"` - The execution context that produced this tool call. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `Direct object { type }` + - `"low"` - - `type: "direct"` + - `"medium"` - - `"direct"` + - `"high"` - - `Program object { caller_id, type }` + - `"auto"` - - `caller_id: string` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - The call ID of the program item that produced this 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`. - - `type: "program"` + - `string` - - `"program"` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `namespace: 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 namespace of the function to run. + - `"1024x1024"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"1024x1536"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"1536x1024"` - - `"in_progress"` + - `"auto"` - - `"completed"` + - `LocalShell object { type }` - - `"incomplete"` + A tool that allows the model to execute shell commands in a local environment. - - `FunctionCallOutput object { id, call_id, output, 5 more }` + - `type: "local_shell"` - - `id: string` + The type of the local shell tool. Always `local_shell`. - The unique ID of the function call tool output. + - `"local_shell"` - - `call_id: string` + - `Shell object { type, allowed_callers, environment }` - The unique ID of the function tool call generated by the model. + A tool that allows the model to execute shell commands. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `type: "shell"` - The output from the function call generated by your code. - Can be a string or an list of output content. + The type of the shell tool. Always `shell`. - - `StringOutput = string` + - `"shell"` - A string of the output of the function call. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The tool invocation context(s). - Text, image, or file output of the function call. + - `"direct"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `"programmatic"` - A text input to the model. + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `BetaLocalEnvironment object { type, skills }` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `BetaContainerReference object { container_id, type }` - A file input to the model. + - `Custom object { name, type, allowed_callers, 3 more }` - - `status: "in_progress" or "completed" or "incomplete"` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `name: string` - - `"in_progress"` + The name of the custom tool, used to identify it in tool calls. - - `"completed"` + - `type: "custom"` - - `"incomplete"` + The type of the custom tool. Always `custom`. - - `type: "function_call_output"` + - `"custom"` - The type of the function tool call output. Always `function_call_output`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"function_call_output"` + The tool invocation context(s). - - `agent: optional object { agent_name }` + - `"direct"` - The agent that produced this item. + - `"programmatic"` - - `agent_name: string` + - `defer_loading: optional boolean` - The canonical name of the agent that produced this item. + Whether this tool should be deferred and discovered via tool search. - - `caller: optional object { type } or object { caller_id, type }` + - `description: optional string` - The execution context that produced this tool call. + Optional description of the custom tool, used to provide more context. - - `Direct object { type }` + - `format: optional object { type } or object { definition, syntax, type }` - - `type: "direct"` + The input format for the custom tool. Default is unconstrained text. - The caller type. Always `direct`. + - `Text object { type }` - - `"direct"` + Unconstrained free-form text. - - `Program object { caller_id, type }` + - `type: "text"` - - `caller_id: string` + Unconstrained text format. Always `text`. - The call ID of the program item that produced this tool call. + - `"text"` - - `type: "program"` + - `Grammar object { definition, syntax, type }` - The caller type. Always `program`. + A grammar defined by the user. - - `"program"` + - `definition: string` - - `created_by: optional string` + The grammar definition. - The identifier of the actor that created the item. + - `syntax: "lark" or "regex"` - - `AgentMessage object { id, author, content, 3 more }` + The syntax of the grammar definition. One of `lark` or `regex`. - - `id: string` + - `"lark"` - The unique ID of the agent message. + - `"regex"` - - `author: string` + - `type: "grammar"` - The sending agent identity. + Grammar format. Always `grammar`. - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + - `"grammar"` - Encrypted content sent between agents. + - `Namespace object { description, name, tools, type }` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + Groups function/custom tools under a shared namespace. - A text input to the model. + - `description: string` - - `BetaResponseOutputText object { annotations, logprobs, text, type }` + A description of the namespace shown to the model. - A text output from the model. + - `name: string` - - `Text object { text, type }` + The namespace name used in tool calls (for example, `crm`). - A text content. + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `text: string` + The function/custom tools available inside this namespace. - - `type: "text"` + - `Function object { name, type, allowed_callers, 5 more }` - - `"text"` + - `name: string` - - `SummaryText object { text, type }` + - `type: "function"` - A summary text from the model. + - `"function"` - - `text: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - A summary of the reasoning output from the model so far. + The tool invocation context(s). - - `type: "summary_text"` + - `"direct"` - The type of the object. Always `summary_text`. + - `"programmatic"` - - `"summary_text"` + - `defer_loading: optional boolean` - - `ReasoningText object { text, type }` + Whether this function should be deferred and discovered via tool search. - Reasoning text from the model. + - `description: optional string` - - `text: string` + - `output_schema: optional map[unknown]` - The reasoning text from the model. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `type: "reasoning_text"` + - `parameters: optional unknown` - The type of the reasoning text. Always `reasoning_text`. + - `strict: optional boolean` - - `"reasoning_text"` + 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. - - `BetaResponseOutputRefusal object { refusal, type }` + - `Custom object { name, type, allowed_callers, 3 more }` - A refusal from the model. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `BetaResponseInputImage 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 custom tool, used to identify it in tool calls. - - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` + - `type: "custom"` - A screenshot of a computer. + The type of the custom tool. Always `custom`. - - `detail: "low" or "high" or "auto" or "original"` + - `"custom"` - The detail level of the screenshot 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: string` + Whether this tool should be deferred and discovered via tool search. - The identifier of an uploaded file that contains the screenshot. + - `description: optional string` - - `image_url: string` + Optional description of the custom tool, used to provide more context. - The URL of the screenshot image. + - `format: optional object { type } or object { definition, syntax, type }` - - `type: "computer_screenshot"` + The input format for the custom tool. Default is unconstrained text. - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `Text object { type }` - - `"computer_screenshot"` + Unconstrained free-form text. - - `prompt_cache_breakpoint: optional object { mode }` + - `type: "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. + Unconstrained text format. Always `text`. - - `mode: "explicit"` + - `"text"` - The breakpoint mode. Always `explicit`. + - `Grammar object { definition, syntax, type }` - - `"explicit"` + A grammar defined by the user. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `definition: string` - A file input to the model. + The grammar definition. - - `EncryptedContent object { encrypted_content, type }` + - `syntax: "lark" or "regex"` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + The syntax of the grammar definition. One of `lark` or `regex`. - - `encrypted_content: string` + - `"lark"` - Opaque encrypted content. + - `"regex"` - - `type: "encrypted_content"` + - `type: "grammar"` - The type of the input item. Always `encrypted_content`. + Grammar format. Always `grammar`. - - `"encrypted_content"` + - `"grammar"` - - `recipient: string` + - `type: "namespace"` - The destination agent identity. + The type of the tool. Always `namespace`. - - `type: "agent_message"` + - `"namespace"` - The type of the item. Always `agent_message`. + - `ToolSearch object { type, description, execution, parameters }` - - `"agent_message"` + Hosted or BYOT tool search configuration for deferred tools. - - `agent: optional object { agent_name }` + - `type: "tool_search"` - The agent that produced this item. + The type of the tool. Always `tool_search`. - - `agent_name: string` + - `"tool_search"` - The canonical name of the agent that produced this item. + - `description: optional string` - - `MultiAgentCall object { id, action, arguments, 3 more }` + Description shown to the model for a client-executed tool search tool. - - `id: string` + - `execution: optional "server" or "client"` - The unique ID of the multi-agent call item. + Whether tool search is executed by the server or by the client. - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `"server"` - The multi-agent action to execute. + - `"client"` - - `"spawn_agent"` + - `parameters: optional unknown` - - `"interrupt_agent"` + Parameter schema for a client-executed tool search tool. - - `"list_agents"` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `"send_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). - - `"followup_task"` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `"wait_agent"` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `arguments: string` + - `"web_search_preview"` - The JSON string of arguments generated for the action. + - `"web_search_preview_2025_03_11"` - - `call_id: string` + - `search_content_types: optional array of "text" or "image"` - The unique ID linking this call to its output. + - `"text"` - - `type: "multi_agent_call"` + - `"image"` - The type of the multi-agent call. Always `multi_agent_call`. + - `search_context_size: optional "low" or "medium" or "high"` - - `"multi_agent_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. - - `agent: optional object { agent_name }` + - `"low"` - The agent that produced this item. + - `"medium"` - - `agent_name: string` + - `"high"` - The canonical name of the agent that produced this item. + - `user_location: optional object { type, city, country, 2 more }` - - `MultiAgentCallOutput object { id, action, call_id, 3 more }` + The user's location. - - `id: string` + - `type: "approximate"` - The unique ID of the multi-agent call output item. + The type of location approximation. Always `approximate`. - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `"approximate"` - The multi-agent action that produced this result. + - `city: optional string` - - `"spawn_agent"` + Free text input for the city of the user, e.g. `San Francisco`. - - `"interrupt_agent"` + - `country: optional string` - - `"list_agents"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"send_message"` + - `region: optional string` - - `"followup_task"` + Free text input for the region of the user, e.g. `California`. - - `"wait_agent"` + - `timezone: optional string` - - `call_id: string` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The unique ID of the multi-agent call. + - `ApplyPatch object { type, allowed_callers }` - - `output: array of BetaResponseOutputText` + Allows the assistant to create, delete, or update files using unified diffs. - Text output returned by the multi-agent action. + - `type: "apply_patch"` - - `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 type of the tool. Always `apply_patch`. - The annotations of the text output. + - `"apply_patch"` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `text: string` + The tool invocation context(s). - The text output from the model. + - `"direct"` - - `type: "output_text"` + - `"programmatic"` - The type of the output text. Always `output_text`. +- `top_logprobs: optional number` - - `type: "multi_agent_call_output"` + 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. - The type of the multi-agent result. Always `multi_agent_call_output`. +- `top_p: optional number` - - `"multi_agent_call_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. - - `agent: optional object { agent_name }` + We generally recommend altering this or `temperature` but not both. - The agent that produced this item. +- `truncation: optional "auto" or "disabled"` - - `agent_name: string` + The truncation strategy to use for the model response. - The canonical name of the agent that produced this item. + - `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. - - `WebSearchCall object { id, action, status, 2 more }` + - `"auto"` - The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + - `"disabled"` - - `id: string` +- `user: optional string` - The unique ID of the web search tool call. + 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). - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` +### Returns - 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). +- `BetaResponse object { id, created_at, error, 32 more }` - - `Search object { type, queries, query, sources }` + - `id: string` - Action type "search" - Performs a web search query. + Unique identifier for this Response. - - `type: "search"` + - `created_at: number` - The action type. + Unix timestamp (in seconds) of when this Response was created. - - `"search"` + - `error: BetaResponseError` - - `queries: optional array of string` + An error object returned when the model fails to generate a Response. - The search queries. + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 17 more` - - `query: optional string` + The error code for the response. - The search query. + - `"server_error"` - - `sources: optional array of object { type, url }` + - `"rate_limit_exceeded"` - The sources used in the search. + - `"invalid_prompt"` - - `type: "url"` + - `"data_residency_mismatch"` - The type of source. Always `url`. + - `"bio_policy"` - - `"url"` + - `"vector_store_timeout"` - - `url: string` + - `"invalid_image"` - The URL of the source. + - `"invalid_image_format"` - - `OpenPage object { type, url }` + - `"invalid_base64_image"` - Action type "open_page" - Opens a specific URL from search results. + - `"invalid_image_url"` - - `type: "open_page"` + - `"image_too_large"` - The action type. + - `"image_too_small"` - - `"open_page"` + - `"image_parse_error"` - - `url: optional string` + - `"image_content_policy_violation"` - The URL opened by the model. + - `"invalid_image_mode"` - - `FindInPage object { pattern, type, url }` + - `"image_file_too_large"` - Action type "find_in_page": Searches for a pattern within a loaded page. + - `"unsupported_image_media_type"` - - `pattern: string` + - `"empty_image_file"` - The pattern or text to search for within the page. + - `"failed_to_download_image"` - - `type: "find_in_page"` + - `"image_file_not_found"` - The action type. + - `message: string` - - `"find_in_page"` + A human-readable description of the error. - - `url: string` + - `incomplete_details: object { reason }` - The URL of the page searched for the pattern. + Details about why the response is incomplete. - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `reason: optional "max_output_tokens" or "content_filter"` - The status of the web search tool call. + The reason why the response is incomplete. - - `"in_progress"` + - `"max_output_tokens"` - - `"searching"` + - `"content_filter"` - - `"completed"` + - `instructions: string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - - `"failed"` + A system (or developer) message inserted into the model's context. - - `type: "web_search_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. - The type of the web search tool call. Always `web_search_call`. + - `string` - - `"web_search_call"` + A text input to the model, equivalent to a text input with the + `developer` role. - - `agent: optional object { agent_name }` + - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - The agent that produced this item. + A list of one or many input items to the model, containing + different content types. - - `agent_name: string` + - `BetaEasyInputMessage object { content, role, phase, type }` - The canonical name of the agent that produced this 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. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + - `content: string or BetaResponseInputMessageContentList` - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `id: string` + - `TextInput = string` - The unique ID of the computer call. + A text input to the model. - - `call_id: string` + - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` - An identifier used when responding to the tool call with output. + A list of one or many input items to the model, containing different content + types. - - `pending_safety_checks: array of object { id, code, message }` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - The pending safety checks for the computer call. + A text input to the model. - - `id: string` + - `text: string` - The ID of the pending safety check. + The text input to the model. - - `code: optional string` + - `type: "input_text"` - The type of the pending safety check. + The type of the input item. Always `input_text`. - - `message: optional string` + - `"input_text"` - Details about the pending safety check. + - `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 item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `mode: "explicit"` - - `"in_progress"` + The breakpoint mode. Always `explicit`. - - `"completed"` + - `"explicit"` - - `"incomplete"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `type: "computer_call"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - The type of the computer call. Always `computer_call`. + - `detail: "low" or "high" or "auto" or "original"` - - `"computer_call"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `action: optional BetaComputerAction` + - `"low"` - A click action. + - `"high"` - - `actions: optional BetaComputerActionList` + - `"auto"` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `"original"` - - `agent: optional object { agent_name }` + - `type: "input_image"` - The agent that produced this item. + The type of the input item. Always `input_image`. - - `agent_name: string` + - `"input_image"` - The canonical name of the agent that produced this item. + - `file_id: optional string` - - `ComputerCallOutput object { id, call_id, output, 5 more }` + The ID of the file to be sent to the model. - - `id: string` + - `image_url: optional string` - The unique ID of the computer call tool output. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `call_id: string` + - `prompt_cache_breakpoint: optional object { mode }` - The ID of the computer tool call that produced the 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. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `mode: "explicit"` - A computer screenshot image used with the computer use tool. + The breakpoint mode. Always `explicit`. - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + - `"explicit"` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `"completed"` + A file input to the model. - - `"incomplete"` + - `type: "input_file"` - - `"failed"` + The type of the input item. Always `input_file`. - - `"in_progress"` + - `"input_file"` - - `type: "computer_call_output"` + - `detail: optional "auto" or "low" or "high"` - The type of the computer tool call output. Always `computer_call_output`. + 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`. - - `"computer_call_output"` + - `"auto"` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `"low"` - The safety checks reported by the API that have been acknowledged by the - developer. + - `"high"` - - `id: string` + - `file_data: optional string` - The ID of the pending safety check. + The content of the file to be sent to the model. - - `code: optional string` + - `file_id: optional string` - The type of the pending safety check. + The ID of the file to be sent to the model. - - `message: optional string` + - `file_url: optional string` - Details about the pending safety check. + The URL of the file to be sent to the model. - - `agent: optional object { agent_name }` + - `filename: optional string` - The agent that produced this item. + The name of the file to be sent to the model. - - `agent_name: string` + - `prompt_cache_breakpoint: optional object { mode }` - The canonical name of the agent that produced this item. + 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. - - `created_by: optional string` + - `mode: "explicit"` - The identifier of the actor that created the item. + The breakpoint mode. Always `explicit`. - - `Reasoning object { id, summary, type, 4 more }` + - `"explicit"` - 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). + - `role: "user" or "assistant" or "system" or "developer"` - - `id: string` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - The unique identifier of the reasoning content. + - `"user"` - - `summary: array of object { text, type }` + - `"assistant"` - Reasoning summary content. + - `"system"` - - `text: string` + - `"developer"` - A summary of the reasoning output from the model so far. + - `phase: optional "commentary" or "final_answer"` - - `type: "summary_text"` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - The type of the object. Always `summary_text`. + - `"commentary"` - - `"summary_text"` + - `"final_answer"` - - `type: "reasoning"` + - `type: optional "message"` - The type of the object. Always `reasoning`. + The type of the message input. Always `message`. - - `"reasoning"` + - `"message"` - - `agent: optional object { agent_name }` + - `Message object { content, role, agent, 2 more }` - The agent that produced this 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. - - `agent_name: string` + - `content: BetaResponseInputMessageContentList` - The canonical name of the agent that produced this item. + A list of one or many input items to the model, containing different content + types. - - `content: optional array of object { text, type }` + - `role: "user" or "system" or "developer"` - Reasoning text content. + The role of the message input. One of `user`, `system`, or `developer`. - - `text: string` + - `"user"` - The reasoning text from the model. + - `"system"` - - `type: "reasoning_text"` + - `"developer"` - The type of the reasoning text. Always `reasoning_text`. + - `agent: optional object { agent_name }` - - `"reasoning_text"` + The agent that produced this item. - - `encrypted_content: optional string` + - `agent_name: 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 canonical name of the agent that produced this item. - `status: optional "in_progress" or "completed" or "incomplete"` - The status of the item. One of `in_progress`, `completed`, or + The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -35394,256 +36254,262 @@ the `background` parameter set to `true` can be cancelled. - `"incomplete"` - - `Program object { id, call_id, code, 3 more }` + - `type: optional "message"` - - `id: string` + The type of the message input. Always set to `message`. - The unique ID of the program item. + - `"message"` - - `call_id: string` + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - The stable call ID of the program item. + An output message from the model. - - `code: string` + - `id: string` - The JavaScript source executed by programmatic tool calling. + The unique ID of the output message. - - `fingerprint: string` + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - Opaque program replay fingerprint that must be round-tripped. + The content of the output message. - - `type: "program"` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - The type of the item. Always `program`. + A text output from the model. - - `"program"` + - `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 }` - - `agent: optional object { agent_name }` + The annotations of the text output. - The agent that produced this item. + - `FileCitation object { file_id, filename, index, type }` - - `agent_name: string` + A citation to a file. - The canonical name of the agent that produced this item. + - `file_id: string` - - `ProgramOutput object { id, call_id, result, 3 more }` + The ID of the file. - - `id: string` + - `filename: string` - The unique ID of the program output item. + The filename of the file cited. - - `call_id: string` + - `index: number` - The call ID of the program item. + The index of the file in the list of files. - - `result: string` + - `type: "file_citation"` - The result produced by the program item. + The type of the file citation. Always `file_citation`. - - `status: "completed" or "incomplete"` + - `"file_citation"` - The terminal status of the program output item. + - `URLCitation object { end_index, start_index, title, 2 more }` - - `"completed"` + A citation for a web resource used to generate a model response. - - `"incomplete"` + - `end_index: number` - - `type: "program_output"` + The index of the last character of the URL citation in the message. - The type of the item. Always `program_output`. + - `start_index: number` - - `"program_output"` + The index of the first character of the URL citation in the message. - - `agent: optional object { agent_name }` + - `title: string` - The agent that produced this item. + The title of the web resource. - - `agent_name: string` + - `type: "url_citation"` - The canonical name of the agent that produced this item. + The type of the URL citation. Always `url_citation`. - - `ToolSearchCall object { id, arguments, call_id, 5 more }` + - `"url_citation"` - - `id: string` + - `url: string` - The unique ID of the tool search call item. + The URL of the web resource. - - `arguments: unknown` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - Arguments used for the tool search call. + A citation for a container file used to generate a model response. - - `call_id: string` + - `container_id: string` - The unique ID of the tool search call generated by the model. + The ID of the container file. - - `execution: "server" or "client"` + - `end_index: number` - Whether tool search was executed by the server or by the client. + The index of the last character of the container file citation in the message. - - `"server"` + - `file_id: string` - - `"client"` + The ID of the file. - - `status: "in_progress" or "completed" or "incomplete"` + - `filename: string` - The status of the tool search call item that was recorded. + The filename of the container file cited. - - `"in_progress"` + - `start_index: number` - - `"completed"` + The index of the first character of the container file citation in the message. - - `"incomplete"` + - `type: "container_file_citation"` - - `type: "tool_search_call"` + The type of the container file citation. Always `container_file_citation`. - The type of the item. Always `tool_search_call`. + - `"container_file_citation"` - - `"tool_search_call"` + - `FilePath object { file_id, index, type }` - - `agent: optional object { agent_name }` + A path to a file. - The agent that produced this item. + - `file_id: string` - - `agent_name: string` + The ID of the file. - The canonical name of the agent that produced this item. + - `index: number` - - `created_by: optional string` + The index of the file in the list of files. - The identifier of the actor that created the item. + - `type: "file_path"` - - `ToolSearchOutput object { id, call_id, execution, 5 more }` + The type of the file path. Always `file_path`. - - `id: string` + - `"file_path"` - The unique ID of the tool search output item. + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - - `call_id: string` + - `token: string` - The unique ID of the tool search call generated by the model. + - `bytes: array of number` - - `execution: "server" or "client"` + - `logprob: number` - Whether tool search was executed by the server or by the client. + - `top_logprobs: array of object { token, bytes, logprob }` - - `"server"` + - `token: string` - - `"client"` + - `bytes: array of number` - - `status: "in_progress" or "completed" or "incomplete"` + - `logprob: number` - The status of the tool search output item that was recorded. + - `text: string` - - `"in_progress"` + The text output from the model. - - `"completed"` + - `type: "output_text"` - - `"incomplete"` + The type of the output text. Always `output_text`. - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + - `"output_text"` - The loaded tool definitions returned by tool search. + - `BetaResponseOutputRefusal object { refusal, type }` - - `Function object { name, parameters, strict, 5 more }` + A refusal 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). + - `refusal: string` - - `name: string` + The refusal explanation from the model. - The name of the function to call. + - `type: "refusal"` - - `parameters: map[unknown]` + The type of the refusal. Always `refusal`. - A JSON schema object describing the parameters of the function. + - `"refusal"` - - `strict: boolean` + - `role: "assistant"` - Whether strict parameter validation is enforced for this function tool. + The role of the output message. Always `assistant`. - - `type: "function"` + - `"assistant"` - The type of the function tool. Always `function`. + - `status: "in_progress" or "completed" or "incomplete"` - - `"function"` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"in_progress"` - The tool invocation context(s). + - `"completed"` - - `"direct"` + - `"incomplete"` - - `"programmatic"` + - `type: "message"` - - `defer_loading: optional boolean` + The type of the output message. Always `message`. - Whether this function is deferred and loaded via tool search. + - `"message"` - - `description: optional string` + - `agent: optional object { agent_name }` - A description of the function. Used by the model to determine whether or not to call the function. + The agent that produced this item. - - `output_schema: optional map[unknown]` + - `agent_name: string` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The canonical name of the agent that produced this item. - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `phase: optional "commentary" or "final_answer"` - 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). + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `type: "file_search"` + - `"commentary"` - The type of the file search tool. Always `file_search`. + - `"final_answer"` - - `"file_search"` + - `FileSearchCall object { id, queries, status, 3 more }` - - `vector_store_ids: array of string` + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - The IDs of the vector stores to search. + - `id: string` - - `filters: optional object { key, type, value } or object { filters, type }` + The unique ID of the file search tool call. - A filter to apply. + - `queries: array of string` - - `ComparisonFilter object { key, type, value }` + The queries used to search for files. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `key: string` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - The key to compare against the value. + - `"in_progress"` - - `type: "eq" or "ne" or "gt" or 5 more` + - `"searching"` - 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 + - `"incomplete"` - - `"eq"` + - `"failed"` - - `"ne"` + - `type: "file_search_call"` - - `"gt"` + The type of the file search tool call. Always `file_search_call`. - - `"gte"` + - `"file_search_call"` - - `"lt"` + - `agent: optional object { agent_name }` - - `"lte"` + The agent that produced this item. - - `"in"` + - `agent_name: string` - - `"nin"` + The canonical name of the agent that produced this item. - - `value: string or number or boolean or array of string or number` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - The value to compare against the attribute key; supports string, number, or boolean types. + 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` @@ -35651,941 +36517,1026 @@ the `background` parameter set to `true` can be cancelled. - `boolean` - - `array of string or number` + - `file_id: optional string` - - `string` + The unique ID of the file. - - `number` + - `filename: optional string` - - `CompoundFilter object { filters, type }` + The name of the file. - Combine multiple filters using `and` or `or`. + - `score: optional number` - - `filters: array of object { key, type, value } or unknown` + The relevance score of the file - a value between 0 and 1. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `text: optional string` - - `ComparisonFilter object { key, type, value }` + The text that was retrieved from the file. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - - `key: string` + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - The key to compare against the value. + - `id: string` - - `type: "eq" or "ne" or "gt" or 5 more` + The unique ID of the computer call. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `call_id: string` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + An identifier used when responding to the tool call with output. - - `"eq"` + - `pending_safety_checks: array of object { id, code, message }` - - `"ne"` + The pending safety checks for the computer call. - - `"gt"` + - `id: string` - - `"gte"` + The ID of the pending safety check. - - `"lt"` + - `code: optional string` - - `"lte"` + The type of the pending safety check. - - `"in"` + - `message: optional string` - - `"nin"` + Details about the pending safety check. - - `value: string or number or boolean or array of string or number` + - `status: "in_progress" or "completed" or "incomplete"` - The value to compare against the attribute key; supports string, number, or boolean types. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `string` + - `"in_progress"` - - `number` + - `"completed"` - - `boolean` + - `"incomplete"` - - `array of string or number` + - `type: "computer_call"` - - `string` + The type of the computer call. Always `computer_call`. - - `number` + - `"computer_call"` - - `unknown` + - `action: optional BetaComputerAction` - - `type: "and" or "or"` + A click action. - Type of operation: `and` or `or`. + - `Click object { button, type, x, 2 more }` - - `"and"` + A click action. - - `"or"` + - `button: "left" or "right" or "wheel" or 2 more` - - `max_num_results: optional number` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `"left"` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `"right"` - Ranking options for search. + - `"wheel"` - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `"back"` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `"forward"` - - `embedding_weight: number` + - `type: "click"` - The weight of the embedding in the reciprocal ranking fusion. + Specifies the event type. For a click action, this property is always `click`. - - `text_weight: number` + - `"click"` - The weight of the text in the reciprocal ranking fusion. + - `x: number` - - `ranker: optional "auto" or "default-2024-11-15"` + The x-coordinate where the click occurred. - The ranker to use for the file search. + - `y: number` - - `"auto"` + The y-coordinate where the click occurred. - - `"default-2024-11-15"` + - `keys: optional array of string` - - `score_threshold: optional number` + The keys being held while clicking. - 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. + - `DoubleClick object { keys, type, x, y }` - - `Computer object { type }` + A double click action. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `keys: array of string` - - `type: "computer"` + The keys being held while double-clicking. - The type of the computer tool. Always `computer`. + - `type: "double_click"` - - `"computer"` + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `ComputerUsePreview object { display_height, display_width, environment, 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). + - `x: number` - - `display_height: number` + The x-coordinate where the double click occurred. - The height of the computer display. + - `y: number` - - `display_width: number` + The y-coordinate where the double click occurred. - The width of the computer display. + - `Drag object { path, type, keys }` - - `environment: "windows" or "mac" or "linux" or 2 more` + A drag action. - The type of computer environment to control. + - `path: array of object { x, y }` - - `"windows"` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `"mac"` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `"linux"` + - `x: number` - - `"ubuntu"` + The x-coordinate. - - `"browser"` + - `y: number` - - `type: "computer_use_preview"` + The y-coordinate. - The type of the computer use tool. Always `computer_use_preview`. + - `type: "drag"` - - `"computer_use_preview"` + Specifies the event type. For a drag action, this property is always set to `drag`. - - `WebSearch object { type, filters, search_context_size, user_location }` + - `"drag"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + - `keys: optional array of string` - - `type: "web_search" or "web_search_2025_08_26"` + The keys being held while dragging the mouse. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `Keypress object { keys, type }` - - `"web_search"` + A collection of keypresses the model would like to perform. - - `"web_search_2025_08_26"` + - `keys: array of string` - - `filters: optional object { allowed_domains }` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - Filters for the search. + - `type: "keypress"` - - `allowed_domains: optional array of string` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `"keypress"` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `Move object { type, x, y, keys }` - - `search_context_size: optional "low" or "medium" or "high"` + A mouse move action. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `type: "move"` - - `"low"` + Specifies the event type. For a move action, this property is always set to `move`. - - `"medium"` + - `"move"` - - `"high"` + - `x: number` - - `user_location: optional object { city, country, region, 2 more }` + The x-coordinate to move to. - The approximate location of the user. + - `y: number` - - `city: optional string` + The y-coordinate to move to. - Free text input for the city of the user, e.g. `San Francisco`. + - `keys: optional array of string` - - `country: optional string` + The keys being held while moving the mouse. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `Screenshot object { type }` - - `region: optional string` + A screenshot action. - Free text input for the region of the user, e.g. `California`. + - `type: "screenshot"` - - `timezone: optional string` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"screenshot"` - - `type: optional "approximate"` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - The type of location approximation. Always `approximate`. + A scroll action. - - `"approximate"` + - `scroll_x: number` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + The horizontal scroll distance. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + - `scroll_y: number` - - `server_label: string` + The vertical scroll distance. - A label for this MCP server, used to identify it in tool calls. + - `type: "scroll"` - - `type: "mcp"` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - The type of the MCP tool. Always `mcp`. + - `"scroll"` - - `"mcp"` + - `x: number` - - `allowed_callers: optional array of "direct" or "programmatic"` + The x-coordinate where the scroll occurred. - The tool invocation context(s). + - `y: number` - - `"direct"` + The y-coordinate where the scroll occurred. - - `"programmatic"` + - `keys: optional array of string` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + The keys being held while scrolling. - List of allowed tool names or a filter object. + - `Type object { text, type }` - - `McpAllowedTools = array of string` + An action to type in text. - A string array of allowed tool names + - `text: string` - - `McpToolFilter 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. - - `authorization: optional string` + - `type: "wait"` - 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. + Specifies the event type. For a wait action, this property is always set to `wait`. - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `"wait"` - 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). + - `actions: optional BetaComputerActionList` - Currently supported `connector_id` values are: + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - 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` + - `Click object { button, type, x, 2 more }` - - `"connector_dropbox"` + A click action. - - `"connector_gmail"` + - `DoubleClick object { keys, type, x, y }` - - `"connector_googlecalendar"` + A double click action. - - `"connector_googledrive"` + - `Drag object { path, type, keys }` - - `"connector_microsoftteams"` + A drag action. - - `"connector_outlookcalendar"` + - `Keypress object { keys, type }` - - `"connector_outlookemail"` + A collection of keypresses the model would like to perform. - - `"connector_sharepoint"` + - `Move object { type, x, y, keys }` - - `defer_loading: optional boolean` + A mouse move action. - Whether this MCP tool is deferred and discovered via tool search. + - `Screenshot object { type }` - - `headers: optional map[string]` + A screenshot action. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `require_approval: optional object { always, never } or "always" or "never"` + A scroll action. - Specify which of the MCP server's tools require approval. + - `Type object { text, type }` - - `McpToolApprovalFilter object { always, never }` + An action to type in text. - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `Wait object { type }` - - `always: optional object { read_only, tool_names }` + A wait action. - A filter object to specify which tools are allowed. + - `agent: optional object { agent_name }` - - `read_only: optional boolean` + The agent that produced this item. - 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. + - `agent_name: string` - - `tool_names: optional array of string` + The canonical name of the agent that produced this item. - List of allowed tool names. + - `ComputerCallOutput object { call_id, output, type, 4 more }` - - `never: optional object { read_only, tool_names }` + The output of a computer tool call. - 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: BetaResponseComputerToolCallOutputScreenshot` - - `tool_names: optional array of string` + A computer screenshot image used with the computer use tool. - 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"` + - `file_id: optional string` - - `"never"` + The identifier of an uploaded file that contains the screenshot. - - `server_description: optional string` + - `image_url: optional string` - Optional description of the MCP server, used to provide more context. + The URL of the screenshot image. - - `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. + - `id: optional string` - - `CodeInterpreter object { container, type, allowed_callers }` + The ID of the computer tool call output. - A tool that runs Python code to help generate a response to a prompt. + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + The safety checks reported by the API that have been acknowledged by the developer. - 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. + - `id: string` - - `string` + The ID of the pending safety check. - The container ID. + - `code: optional string` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + The type of the pending safety check. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `message: optional string` - - `type: "auto"` + Details about the pending safety check. - Always `auto`. + - `agent: optional object { agent_name }` - - `"auto"` + The agent that produced this item. - - `file_ids: optional array of string` + - `agent_name: string` - An optional list of uploaded files to make available to your code. + The canonical name of the agent that produced this item. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `status: optional "in_progress" or "completed" or "incomplete"` - The memory limit for the code interpreter container. + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - `"1g"` + - `"in_progress"` - - `"4g"` + - `"completed"` - - `"16g"` + - `"incomplete"` - - `"64g"` + - `WebSearchCall object { id, action, status, 2 more }` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - Network access policy for the container. + - `id: string` - - `BetaContainerNetworkPolicyDisabled object { type }` + The unique ID of the web search tool call. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `type: "code_interpreter"` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - The type of the code interpreter tool. Always `code_interpreter`. + - `Search object { type, queries, query, sources }` - - `"code_interpreter"` + Action type "search" - Performs a web search query. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "search"` - The tool invocation context(s). + The action type. - - `"direct"` + - `"search"` - - `"programmatic"` + - `queries: optional array of string` - - `ProgrammaticToolCalling object { type }` + The search queries. - - `type: "programmatic_tool_calling"` + - `query: optional string` - The type of the tool. Always `programmatic_tool_calling`. + The search query. - - `"programmatic_tool_calling"` + - `sources: optional array of object { type, url }` - - `ImageGeneration object { type, action, background, 9 more }` + The sources used in the search. - A tool that generates images using the GPT image models. + - `type: "url"` - - `type: "image_generation"` + The type of source. Always `url`. - The type of the image generation tool. Always `image_generation`. + - `"url"` - - `"image_generation"` + - `url: string` - - `action: optional "generate" or "edit" or "auto"` + The URL of the source. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `OpenPage object { type, url }` - - `"generate"` + Action type "open_page" - Opens a specific URL from search results. - - `"edit"` + - `type: "open_page"` - - `"auto"` + The action type. - - `background: optional "transparent" or "opaque" or "auto"` + - `"open_page"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + - `url: optional string` - - `"transparent"` + The URL opened by the model. - - `"opaque"` + - `FindInPage object { pattern, type, url }` - - `"auto"` + Action type "find_in_page": Searches for a pattern within a loaded page. - - `input_fidelity: optional "high" or "low"` + - `pattern: 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 pattern or text to search for within the page. - - `"high"` + - `type: "find_in_page"` - - `"low"` + The action type. - - `input_image_mask: optional object { file_id, image_url }` + - `"find_in_page"` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `url: string` - - `file_id: optional string` + The URL of the page searched for the pattern. - File ID for the mask image. + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `image_url: optional string` + The status of the web search tool call. - Base64-encoded mask image. + - `"in_progress"` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"searching"` - The image generation model to use. Default: `gpt-image-1`. + - `"completed"` - - `string` + - `"failed"` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `type: "web_search_call"` - The image generation model to use. Default: `gpt-image-1`. + The type of the web search tool call. Always `web_search_call`. - - `"gpt-image-1"` + - `"web_search_call"` - - `"gpt-image-1-mini"` + - `agent: optional object { agent_name }` - - `"gpt-image-1.5"` + The agent that produced this item. - - `moderation: optional "auto" or "low"` + - `agent_name: string` - Moderation level for the generated image. Default: `auto`. + The canonical name of the agent that produced this item. - - `"auto"` + - `FunctionCall object { arguments, call_id, name, 6 more }` - - `"low"` + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `output_compression: optional number` + - `arguments: string` - Compression level for the output image. Default: 100. + A JSON string of the arguments to pass to the function. - - `output_format: optional "png" or "webp" or "jpeg"` + - `call_id: string` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + The unique ID of the function tool call generated by the model. - - `"png"` + - `name: string` - - `"webp"` + The name of the function to run. - - `"jpeg"` + - `type: "function_call"` - - `partial_images: optional number` + The type of the function tool call. Always `function_call`. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `"function_call"` - - `quality: optional "low" or "medium" or "high" or "auto"` + - `id: optional string` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The unique ID of the function tool call. - - `"low"` + - `agent: optional object { agent_name }` - - `"medium"` + The agent that produced this item. - - `"high"` + - `agent_name: string` - - `"auto"` + The canonical name of the agent that produced this item. - - `size: optional string or "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. - - `string` + - `Direct object { type }` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `type: "direct"` - 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`. + - `"direct"` - - `"1024x1024"` + - `Program object { caller_id, type }` - - `"1024x1536"` + - `caller_id: string` - - `"1536x1024"` + The call ID of the program item that produced this tool call. - - `"auto"` + - `type: "program"` - - `LocalShell object { type }` + - `"program"` - A tool that allows the model to execute shell commands in a local environment. + - `namespace: optional string` - - `type: "local_shell"` + The namespace of the function to run. - The type of the local shell tool. Always `local_shell`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"local_shell"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `Shell object { type, allowed_callers, environment }` + - `"in_progress"` - A tool that allows the model to execute shell commands. + - `"completed"` - - `type: "shell"` + - `"incomplete"` - The type of the shell tool. Always `shell`. + - `FunctionCallOutput object { call_id, output, type, 4 more }` - - `"shell"` + The output of a function tool call. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `call_id: string` - The tool invocation context(s). + The unique ID of the function tool call generated by the model. - - `"direct"` + - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - - `"programmatic"` + Text, image, or file output of the function tool call. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `string` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + A JSON string of the output of the function tool call. - - `BetaLocalEnvironment object { type, skills }` + - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - - `BetaContainerReference object { container_id, type }` + An array of content outputs (text, image, file) for the function tool call. - - `Custom object { name, type, allowed_callers, 3 more }` + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + A text input to the model. - - `name: string` + - `text: string` - The name of the custom tool, used to identify it in tool calls. + The text input to the model. - - `type: "custom"` + - `type: "input_text"` - The type of the custom tool. Always `custom`. + The type of the input item. Always `input_text`. - - `"custom"` + - `"input_text"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `prompt_cache_breakpoint: optional object { mode }` - The tool invocation context(s). + 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. - - `"direct"` + - `mode: "explicit"` - - `"programmatic"` + The breakpoint mode. Always `explicit`. - - `defer_loading: optional boolean` + - `"explicit"` - Whether this tool should be deferred and discovered via tool search. + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - - `description: optional string` + An image input to the model. Learn about [image inputs](/docs/guides/vision) - Optional description of the custom tool, used to provide more context. + - `type: "input_image"` - - `format: optional object { type } or object { definition, syntax, type }` + The type of the input item. Always `input_image`. - The input format for the custom tool. Default is unconstrained text. + - `"input_image"` - - `Text object { type }` + - `detail: optional "low" or "high" or "auto" or "original"` - Unconstrained free-form text. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `type: "text"` + - `"low"` - Unconstrained text format. Always `text`. + - `"high"` - - `"text"` + - `"auto"` - - `Grammar object { definition, syntax, type }` + - `"original"` - A grammar defined by the user. + - `file_id: optional string` - - `definition: string` + The ID of the file to be sent to the model. - The grammar definition. + - `image_url: optional string` - - `syntax: "lark" or "regex"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The syntax of the grammar definition. One of `lark` or `regex`. + - `prompt_cache_breakpoint: optional object { mode }` - - `"lark"` + 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. - - `"regex"` + - `mode: "explicit"` - - `type: "grammar"` + The breakpoint mode. Always `explicit`. - Grammar format. Always `grammar`. + - `"explicit"` - - `"grammar"` + - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` - - `Namespace object { description, name, tools, type }` + A file input to the model. - Groups function/custom tools under a shared namespace. + - `type: "input_file"` - - `description: string` + The type of the input item. Always `input_file`. - A description of the namespace shown to the model. + - `"input_file"` - - `name: string` + - `detail: optional "auto" or "low" or "high"` - The namespace name used in tool calls (for example, `crm`). + 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`. - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `"auto"` - The function/custom tools available inside this namespace. + - `"low"` - - `Function object { name, type, allowed_callers, 5 more }` + - `"high"` - - `name: string` + - `file_data: optional string` - - `type: "function"` + The base64-encoded data of the file to be sent to the model. - - `"function"` + - `file_id: optional string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The ID of the file to be sent to the model. - The tool invocation context(s). + - `file_url: optional string` - - `"direct"` + The URL of the file to be sent to the model. - - `"programmatic"` + - `filename: optional string` - - `defer_loading: optional boolean` + The name of the file to be sent to the model. - Whether this function should be deferred and discovered via tool search. + - `prompt_cache_breakpoint: optional object { mode }` - - `description: 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. - - `output_schema: optional map[unknown]` + - `mode: "explicit"` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + The breakpoint mode. Always `explicit`. - - `parameters: optional unknown` + - `"explicit"` - - `strict: optional boolean` + - `type: "function_call_output"` - 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 function tool call output. Always `function_call_output`. - - `Custom object { name, type, allowed_callers, 3 more }` + - `"function_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 unique ID of the function tool call output. Populated when this item is returned via API. - The name of the custom tool, used to identify it in tool calls. + - `agent: optional object { agent_name }` - - `type: "custom"` + The agent that produced this item. - The type of the custom tool. Always `custom`. + - `agent_name: string` - - `"custom"` + The canonical name of the agent that produced this item. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `caller: optional object { type } or object { caller_id, type }` - The tool invocation context(s). + The execution context that produced this tool call. - - `"direct"` + - `Direct object { type }` - - `"programmatic"` + - `type: "direct"` - - `defer_loading: optional boolean` + The caller type. Always `direct`. - Whether this tool should be deferred and discovered via tool search. + - `"direct"` - - `description: optional string` + - `Program object { caller_id, type }` - Optional description of the custom tool, used to provide more context. + - `caller_id: string` - - `format: optional object { type } or object { definition, syntax, type }` + The call ID of the program item that produced this tool call. - The input format for the custom tool. Default is unconstrained text. + - `type: "program"` - - `Text object { type }` + The caller type. Always `program`. - Unconstrained free-form text. + - `"program"` - - `type: "text"` + - `status: optional "in_progress" or "completed" or "incomplete"` - Unconstrained text format. Always `text`. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `"text"` + - `"in_progress"` - - `Grammar object { definition, syntax, type }` + - `"completed"` - A grammar defined by the user. + - `"incomplete"` - - `definition: string` + - `AgentMessage object { author, content, recipient, 3 more }` - The grammar definition. + A message routed between agents. - - `syntax: "lark" or "regex"` + - `author: string` - The syntax of the grammar definition. One of `lark` or `regex`. + The sending agent identity. - - `"lark"` + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - - `"regex"` + Plaintext, image, or encrypted content sent between agents. - - `type: "grammar"` + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - Grammar format. Always `grammar`. + A text input to the model. - - `"grammar"` + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - - `type: "namespace"` + An image input to the model. Learn about [image inputs](/docs/guides/vision) - The type of the tool. Always `namespace`. + - `EncryptedContent object { encrypted_content, type }` - - `"namespace"` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `ToolSearch object { type, description, execution, parameters }` + - `encrypted_content: string` - Hosted or BYOT tool search configuration for deferred tools. + Opaque encrypted content. - - `type: "tool_search"` + - `type: "encrypted_content"` - The type of the tool. Always `tool_search`. + The type of the input item. Always `encrypted_content`. - - `"tool_search"` + - `"encrypted_content"` - - `description: optional string` + - `recipient: string` - Description shown to the model for a client-executed tool search tool. + The destination agent identity. - - `execution: optional "server" or "client"` + - `type: "agent_message"` - Whether tool search is executed by the server or by the client. + The item type. Always `agent_message`. - - `"server"` + - `"agent_message"` - - `"client"` + - `id: optional string` - - `parameters: optional unknown` + The unique ID of this agent message item. - Parameter schema for a client-executed tool search tool. + - `agent: optional object { agent_name }` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + The agent that produced this item. - 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). + - `agent_name: string` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + The canonical name of the agent that produced this item. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `MultiAgentCall object { action, arguments, call_id, 3 more }` - - `"web_search_preview"` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `"web_search_preview_2025_03_11"` + The multi-agent action that was executed. - - `search_content_types: optional array of "text" or "image"` + - `"spawn_agent"` - - `"text"` + - `"interrupt_agent"` - - `"image"` + - `"list_agents"` - - `search_context_size: optional "low" or "medium" or "high"` + - `"send_message"` - 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. + - `"followup_task"` - - `"low"` + - `"wait_agent"` - - `"medium"` + - `arguments: string` - - `"high"` + The action arguments as a JSON string. - - `user_location: optional object { type, city, country, 2 more }` + - `call_id: string` - The user's location. + The unique ID linking this call to its output. - - `type: "approximate"` + - `type: "multi_agent_call"` - The type of location approximation. Always `approximate`. + The item type. Always `multi_agent_call`. - - `"approximate"` + - `"multi_agent_call"` - - `city: optional string` + - `id: optional string` - Free text input for the city of the user, e.g. `San Francisco`. + The unique ID of this multi-agent call. - - `country: optional string` + - `agent: optional object { agent_name }` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The agent that produced this item. - - `region: optional string` + - `agent_name: string` - Free text input for the region of the user, e.g. `California`. + The canonical name of the agent that produced this item. - - `timezone: optional string` + - `MultiAgentCallOutput object { action, call_id, output, 3 more }` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `ApplyPatch object { type, allowed_callers }` + The multi-agent action that produced this result. - Allows the assistant to create, delete, or update files using unified diffs. + - `"spawn_agent"` - - `type: "apply_patch"` + - `"interrupt_agent"` - The type of the tool. Always `apply_patch`. + - `"list_agents"` - - `"apply_patch"` + - `"send_message"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"followup_task"` - The tool invocation context(s). + - `"wait_agent"` - - `"direct"` + - `call_id: string` - - `"programmatic"` + The unique ID of the multi-agent call. - - `type: "tool_search_output"` + - `output: array of object { text, type, annotations }` - The type of the item. Always `tool_search_output`. + Text output returned by the multi-agent action. - - `"tool_search_output"` + - `text: string` - - `agent: optional object { agent_name }` + The text content. - The agent that produced this item. + - `type: "output_text"` - - `agent_name: string` + The content type. Always `output_text`. - The canonical name of the agent that produced this item. + - `"output_text"` - - `created_by: optional string` + - `annotations: optional 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 }` - The identifier of the actor that created the item. + Citations associated with the text content. - - `AdditionalTools object { id, role, tools, 2 more }` + - `FileCitation object { file_id, filename, index, type }` - - `id: string` + - `file_id: string` - The unique ID of the additional tools item. + The ID of the file. - - `role: "unknown" or "user" or "assistant" or 5 more` + - `filename: string` - The role that provided the additional tools. + The filename of the file cited. - - `"unknown"` + - `index: number` - - `"user"` + The index of the file in the list of files. - - `"assistant"` + - `type: "file_citation"` - - `"system"` + The citation type. Always `file_citation`. - - `"critic"` + - `"file_citation"` - - `"discriminator"` + - `URLCitation object { end_index, start_index, title, 2 more }` - - `"developer"` + - `end_index: number` - - `"tool"` + The index of the last character of the citation in the 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` + - `start_index: number` - The additional tool definitions made available at this item. + The index of the first character of the citation in the message. - - `Function object { name, parameters, strict, 5 more }` + - `title: string` - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + The title of the cited resource. - - `name: string` + - `type: "url_citation"` + + The citation type. Always `url_citation`. + + - `"url_citation"` + + - `url: string` + + The URL of the cited resource. + + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + + - `container_id: string` + + The ID of the container. + + - `end_index: number` + + The index of the last character of the citation in the message. + + - `file_id: string` + + The ID of the container file. + + - `filename: string` + + The filename of the container file cited. + + - `start_index: number` + + The index of the first character of the citation in the message. + + - `type: "container_file_citation"` + + The citation type. Always `container_file_citation`. + + - `"container_file_citation"` + + - `type: "multi_agent_call_output"` + + The item type. Always `multi_agent_call_output`. + + - `"multi_agent_call_output"` + + - `id: optional string` + + The unique ID of this multi-agent call output. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `ToolSearchCall object { arguments, type, id, 4 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. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `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, 4 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. @@ -37100,8 +38051,40 @@ the `background` parameter set to `true` can be cancelled. - `BetaContainerNetworkPolicyDisabled object { type }` + - `type: "disabled"` + + Disable outbound network access. Always `disabled`. + + - `"disabled"` + - `BetaContainerNetworkPolicyAllowlist 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 BetaContainerNetworkPolicyDomainSecret` + + 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`. @@ -37282,10 +38265,128 @@ the `background` parameter set to `true` can be cancelled. - `BetaContainerAuto 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 BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `BetaContainerNetworkPolicyDisabled object { type }` + + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `skills: optional array of BetaSkillReference or BetaInlineSkill` + + An optional list of skills referenced by id or inline data. + + - `BetaSkillReference 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. + + - `BetaInlineSkill object { description, name, source, type }` + + - `description: string` + + The description of the skill. + + - `name: string` + + The name of the skill. + + - `source: BetaInlineSkillSource` + + 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"` + - `BetaLocalEnvironment object { type, skills }` + - `type: "local"` + + Use a local computer environment. + + - `"local"` + + - `skills: optional array of BetaLocalSkill` + + 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. + - `BetaContainerReference 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) @@ -37570,11 +38671,15 @@ the `background` parameter set to `true` can be cancelled. - `"programmatic"` - - `type: "additional_tools"` + - `type: "tool_search_output"` - The type of the item. Always `additional_tools`. + The item type. Always `tool_search_output`. - - `"additional_tools"` + - `"tool_search_output"` + + - `id: optional string` + + The unique ID of this tool search output. - `agent: optional object { agent_name }` @@ -37584,3333 +38689,3016 @@ the `background` parameter set to `true` can be cancelled. The canonical name of the agent that produced this item. - - `Compaction object { id, encrypted_content, type, 2 more }` + - `call_id: optional string` - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + The unique ID of the tool search call generated by the model. - - `id: string` + - `execution: optional "server" or "client"` - The unique ID of the compaction item. + Whether tool search was executed by the server or by the client. - - `encrypted_content: string` + - `"server"` - The encrypted content that was produced by compaction. + - `"client"` - - `type: "compaction"` + - `status: optional "in_progress" or "completed" or "incomplete"` - The type of the item. Always `compaction`. + The status of the tool search output. - - `"compaction"` + - `"in_progress"` - - `agent: optional object { agent_name }` + - `"completed"` - The agent that produced this item. + - `"incomplete"` - - `agent_name: string` + - `AdditionalTools object { role, tools, type, 2 more }` - The canonical name of the agent that produced this item. + - `role: "developer"` - - `created_by: optional string` + The role that provided the additional tools. Only `developer` is supported. - The identifier of the actor that created the item. + - `"developer"` - - `ImageGenerationCall object { id, result, status, 2 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` - An image generation request made by the model. + A list of additional tools made available at this item. - - `id: string` + - `Function object { name, parameters, strict, 5 more }` - The unique ID of the image generation call. + 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). - - `result: string` + - `name: string` - The generated image encoded in base64. + The name of the function to call. - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `parameters: map[unknown]` - The status of the image generation call. + A JSON schema object describing the parameters of the function. - - `"in_progress"` + - `strict: boolean` - - `"completed"` + Whether strict parameter validation is enforced for this function tool. - - `"generating"` + - `type: "function"` - - `"failed"` + The type of the function tool. Always `function`. - - `type: "image_generation_call"` + - `"function"` - The type of the image generation call. Always `image_generation_call`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"image_generation_call"` + The tool invocation context(s). - - `agent: optional object { agent_name }` + - `"direct"` - The agent that produced this item. + - `"programmatic"` - - `agent_name: string` + - `defer_loading: optional boolean` - The canonical name of the agent that produced this item. + Whether this function is deferred and loaded via tool search. - - `CodeInterpreterCall object { id, code, container_id, 4 more }` + - `description: optional string` - A tool call to run code. + A description of the function. Used by the model to determine whether or not to call the function. - - `id: string` + - `output_schema: optional map[unknown]` - The unique ID of the code interpreter tool call. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `code: string` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - The code to run, or null if not available. + 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). - - `container_id: string` + - `type: "file_search"` - The ID of the container used to run the code. + The type of the file search tool. Always `file_search`. - - `outputs: array of object { logs, type } or object { type, url }` + - `"file_search"` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `vector_store_ids: array of string` - - `Logs object { logs, type }` + The IDs of the vector stores to search. - The logs output from the code interpreter. + - `filters: optional object { key, type, value } or object { filters, type }` - - `logs: string` + A filter to apply. - The logs output from the code interpreter. + - `ComparisonFilter object { key, type, value }` - - `type: "logs"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The type of the output. Always `logs`. + - `key: string` - - `"logs"` + The key to compare against the value. - - `Image object { type, url }` + - `type: "eq" or "ne" or "gt" or 5 more` - The image output from the code interpreter. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `type: "image"` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - The type of the output. Always `image`. + - `"eq"` - - `"image"` + - `"ne"` - - `url: string` + - `"gt"` - The URL of the image output from the code interpreter. + - `"gte"` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `"lt"` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `"lte"` - - `"in_progress"` + - `"in"` - - `"completed"` + - `"nin"` - - `"incomplete"` + - `value: string or number or boolean or array of string or number` - - `"interpreting"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `"failed"` + - `string` - - `type: "code_interpreter_call"` + - `number` - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `boolean` - - `"code_interpreter_call"` + - `array of string or number` - - `agent: optional object { agent_name }` + - `string` - The agent that produced this item. + - `number` - - `agent_name: string` + - `CompoundFilter object { filters, type }` - The canonical name of the agent that produced this item. + Combine multiple filters using `and` or `or`. - - `LocalShellCall object { id, action, call_id, 3 more }` + - `filters: array of object { key, type, value } or unknown` - A tool call to run a command on the local shell. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `id: string` + - `ComparisonFilter object { key, type, value }` - The unique ID of the local shell call. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `action: object { command, env, type, 3 more }` + - `key: string` - Execute a shell command on the server. + The key to compare against the value. - - `command: array of string` + - `type: "eq" or "ne" or "gt" or 5 more` - The command to run. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `env: map[string]` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - Environment variables to set for the command. + - `"eq"` - - `type: "exec"` + - `"ne"` - The type of the local shell action. Always `exec`. + - `"gt"` - - `"exec"` + - `"gte"` - - `timeout_ms: optional number` + - `"lt"` - Optional timeout in milliseconds for the command. + - `"lte"` - - `user: optional string` + - `"in"` - Optional user to run the command as. + - `"nin"` - - `working_directory: optional string` + - `value: string or number or boolean or array of string or number` - Optional working directory to run the command in. + The value to compare against the attribute key; supports string, number, or boolean types. - - `call_id: string` + - `string` - The unique ID of the local shell tool call generated by the model. + - `number` - - `status: "in_progress" or "completed" or "incomplete"` + - `boolean` - The status of the local shell call. + - `array of string or number` - - `"in_progress"` + - `string` - - `"completed"` + - `number` - - `"incomplete"` + - `unknown` - - `type: "local_shell_call"` + - `type: "and" or "or"` - The type of the local shell call. Always `local_shell_call`. + Type of operation: `and` or `or`. - - `"local_shell_call"` + - `"and"` - - `agent: optional object { agent_name }` + - `"or"` - The agent that produced this item. + - `max_num_results: optional number` - - `agent_name: string` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - The canonical name of the agent that produced this item. + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `LocalShellCallOutput object { id, output, type, 2 more }` + Ranking options for search. - The output of a local shell tool call. + - `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 local shell tool call generated by the model. + - `embedding_weight: number` - - `output: string` + The weight of the embedding in the reciprocal ranking fusion. - A JSON string of the output of the local shell tool call. + - `text_weight: number` - - `type: "local_shell_call_output"` + The weight of the text in the reciprocal ranking fusion. - The type of the local shell tool call output. Always `local_shell_call_output`. + - `ranker: optional "auto" or "default-2024-11-15"` - - `"local_shell_call_output"` + The ranker to use for the file search. - - `agent: optional object { agent_name }` + - `"auto"` - The agent that produced this item. + - `"default-2024-11-15"` - - `agent_name: string` + - `score_threshold: optional number` - The canonical name of the agent that produced this item. + 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. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `Computer object { type }` - The status of the item. One of `in_progress`, `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). - - `"in_progress"` + - `type: "computer"` - - `"completed"` + The type of the computer tool. Always `computer`. - - `"incomplete"` + - `"computer"` - - `ShellCall object { id, action, call_id, 6 more }` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - A tool call that executes one or more shell commands in a managed environment. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `id: string` + - `display_height: number` - The unique ID of the shell tool call. Populated when this item is returned via API. + The height of the computer display. - - `action: object { commands, max_output_length, timeout_ms }` + - `display_width: number` - The shell commands and limits that describe how to run the tool call. + The width of the computer display. - - `commands: array of string` + - `environment: "windows" or "mac" or "linux" or 2 more` - - `max_output_length: number` + The type of computer environment to control. - Optional maximum number of characters to return from each command. + - `"windows"` - - `timeout_ms: number` + - `"mac"` - Optional timeout in milliseconds for the commands. + - `"linux"` - - `call_id: string` + - `"ubuntu"` - The unique ID of the shell tool call generated by the model. + - `"browser"` - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + - `type: "computer_use_preview"` - Represents the use of a local environment to perform shell actions. + The type of the computer use tool. Always `computer_use_preview`. - - `BetaResponseLocalEnvironment object { type }` + - `"computer_use_preview"` - Represents the use of a local environment to perform shell actions. + - `WebSearch object { type, filters, search_context_size, user_location }` - - `type: "local"` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - The environment type. Always `local`. + - `type: "web_search" or "web_search_2025_08_26"` - - `"local"` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `BetaResponseContainerReference object { container_id, type }` + - `"web_search"` - Represents a container created with /v1/containers. + - `"web_search_2025_08_26"` - - `container_id: string` + - `filters: optional object { allowed_domains }` - - `type: "container_reference"` + Filters for the search. - The environment type. Always `container_reference`. + - `allowed_domains: optional array of string` - - `"container_reference"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `status: "in_progress" or "completed" or "incomplete"` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `search_context_size: optional "low" or "medium" or "high"` - - `"in_progress"` + 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. - - `"completed"` + - `"low"` - - `"incomplete"` + - `"medium"` - - `type: "shell_call"` + - `"high"` - The type of the item. Always `shell_call`. + - `user_location: optional object { city, country, region, 2 more }` - - `"shell_call"` + The approximate location of the user. - - `agent: optional object { agent_name }` + - `city: optional string` - The agent that produced this item. + Free text input for the city of the user, e.g. `San Francisco`. - - `agent_name: string` + - `country: optional string` - The canonical name of the agent that produced this item. + 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"` + - `type: optional "approximate"` - - `Program object { caller_id, type }` + The type of location approximation. Always `approximate`. - - `caller_id: string` + - `"approximate"` - The call ID of the program item that produced this tool call. + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `type: "program"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `"program"` + - `server_label: string` - - `created_by: optional string` + A label for this MCP server, used to identify it in tool calls. - The ID of the entity that created this tool call. + - `type: "mcp"` - - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` + The type of the MCP tool. Always `mcp`. - The output of a shell tool call that was emitted. + - `"mcp"` - - `id: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The unique ID of the shell call output. Populated when this item is returned via API. + The tool invocation context(s). - - `call_id: string` + - `"direct"` - The unique ID of the shell tool call generated by the model. + - `"programmatic"` - - `max_output_length: number` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + List of allowed tool names or a filter object. - - `output: array of object { outcome, stderr, stdout, created_by }` + - `McpAllowedTools = array of string` - An array of shell call output contents + A string array of allowed tool names - - `outcome: object { type } or object { exit_code, type }` + - `McpToolFilter object { read_only, tool_names }` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + A filter object to specify which tools are allowed. - - `Timeout object { type }` + - `read_only: optional boolean` - Indicates that the shell call exceeded its configured time limit. + 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: "timeout"` + - `tool_names: optional array of string` - The outcome type. Always `timeout`. + List of allowed tool names. - - `"timeout"` + - `authorization: optional string` - - `Exit object { exit_code, type }` + 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. - Indicates that the shell commands finished and returned an exit code. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `exit_code: number` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). - Exit code from the shell process. + Currently supported `connector_id` values are: - - `type: "exit"` + - 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 outcome type. Always `exit`. + - `"connector_dropbox"` - - `"exit"` + - `"connector_gmail"` - - `stderr: string` + - `"connector_googlecalendar"` - The standard error output that was captured. + - `"connector_googledrive"` - - `stdout: string` + - `"connector_microsoftteams"` - The standard output that was captured. + - `"connector_outlookcalendar"` - - `created_by: optional string` + - `"connector_outlookemail"` - The identifier of the actor that created the item. + - `"connector_sharepoint"` - - `status: "in_progress" or "completed" or "incomplete"` + - `defer_loading: optional boolean` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + Whether this MCP tool is deferred and discovered via tool search. - - `"in_progress"` + - `headers: optional map[string]` - - `"completed"` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `"incomplete"` + - `require_approval: optional object { always, never } or "always" or "never"` - - `type: "shell_call_output"` + Specify which of the MCP server's tools require approval. - The type of the shell call output. Always `shell_call_output`. + - `McpToolApprovalFilter object { always, never }` - - `"shell_call_output"` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `agent: optional object { agent_name }` + - `always: optional object { read_only, tool_names }` - The agent that produced this item. + A filter object to specify which tools are allowed. - - `agent_name: string` + - `read_only: optional boolean` - The canonical name of the agent that produced this item. + 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 }` + - `never: optional 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"` + - `McpToolApprovalSetting = "always" or "never"` - - `"program"` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `created_by: optional string` + - `"always"` - The identifier of the actor that created the item. + - `"never"` - - `ApplyPatchCall object { id, call_id, operation, 5 more }` + - `server_description: optional string` - A tool call that applies file diffs by creating, deleting, or updating files. + Optional description of the MCP server, used to provide more context. - - `id: string` + - `server_url: optional string` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `call_id: string` + - `tunnel_id: optional string` - The unique ID of the apply patch tool call generated by 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. - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `CodeInterpreter object { container, type, allowed_callers }` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + A tool that runs Python code to help generate a response to a prompt. - - `CreateFile object { diff, path, type }` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - Instruction describing how to create a file via the apply_patch tool. + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - - `diff: string` + - `string` - Diff to apply. + The container ID. - - `path: string` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - Path of the file to create. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `type: "create_file"` + - `type: "auto"` - Create a new file with the provided diff. + Always `auto`. - - `"create_file"` + - `"auto"` - - `DeleteFile object { path, type }` + - `file_ids: optional array of string` - Instruction describing how to delete a file via the apply_patch tool. + An optional list of uploaded files to make available to your code. - - `path: string` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - Path of the file to delete. + The memory limit for the code interpreter container. - - `type: "delete_file"` + - `"1g"` - Delete the specified file. + - `"4g"` - - `"delete_file"` + - `"16g"` - - `UpdateFile object { diff, path, type }` + - `"64g"` - Instruction describing how to update a file via the apply_patch tool. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `diff: string` + Network access policy for the container. - Diff to apply. + - `BetaContainerNetworkPolicyDisabled object { type }` - - `path: string` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - Path of the file to update. + - `type: "code_interpreter"` - - `type: "update_file"` + The type of the code interpreter tool. Always `code_interpreter`. - Update an existing file with the provided diff. + - `"code_interpreter"` - - `"update_file"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `status: "in_progress" or "completed"` + The tool invocation context(s). - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `"direct"` - - `"in_progress"` + - `"programmatic"` - - `"completed"` + - `ProgrammaticToolCalling object { type }` - - `type: "apply_patch_call"` + - `type: "programmatic_tool_calling"` - The type of the item. Always `apply_patch_call`. + The type of the tool. Always `programmatic_tool_calling`. - - `"apply_patch_call"` + - `"programmatic_tool_calling"` - - `agent: optional object { agent_name }` + - `ImageGeneration object { type, action, background, 9 more }` - The agent that produced this item. + A tool that generates images using the GPT image models. - - `agent_name: string` + - `type: "image_generation"` - The canonical name of the agent that produced this item. + 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 ID of the entity that created this tool call. + - `input_fidelity: optional "high" or "low"` - - `ApplyPatchCallOutput object { id, call_id, status, 5 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 output emitted by an apply patch tool call. + - `"high"` - - `id: string` + - `"low"` - The unique ID of the apply patch tool call output. 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` - - `status: "completed" or "failed"` + File ID for the mask image. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `image_url: optional string` - - `"completed"` + Base64-encoded mask image. - - `"failed"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `type: "apply_patch_call_output"` + The image generation model to use. Default: `gpt-image-1`. - The type of the item. Always `apply_patch_call_output`. + - `string` - - `"apply_patch_call_output"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `agent: optional object { agent_name }` + The image generation model to use. Default: `gpt-image-1`. - The agent that produced this item. + - `"gpt-image-1"` - - `agent_name: string` + - `"gpt-image-1-mini"` - The canonical name of the agent that produced this item. + - `"gpt-image-1.5"` - - `caller: optional object { type } or object { caller_id, type }` + - `moderation: optional "auto" or "low"` - The execution context that produced this tool call. + Moderation level for the generated image. Default: `auto`. - - `Direct object { type }` + - `"auto"` - - `type: "direct"` + - `"low"` - - `"direct"` + - `output_compression: optional number` - - `Program object { caller_id, type }` + Compression level for the output image. Default: 100. - - `caller_id: string` + - `output_format: optional "png" or "webp" or "jpeg"` - The call ID of the program item that produced this tool call. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `type: "program"` + - `"png"` - - `"program"` + - `"webp"` - - `created_by: optional string` + - `"jpeg"` - The ID of the entity that created this tool call output. + - `partial_images: optional number` - - `output: optional string` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - Optional textual output returned by the apply patch tool. + - `quality: optional "low" or "medium" or "high" or "auto"` - - `McpCall object { id, arguments, name, 7 more }` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - An invocation of a tool on an MCP server. + - `"low"` - - `id: string` + - `"medium"` - The unique ID of the tool call. + - `"high"` - - `arguments: string` + - `"auto"` - A JSON string of the arguments passed to the tool. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `name: string` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - The name of the tool that was run. + - `string` - - `server_label: string` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - The label of the MCP server running the tool. + 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: "mcp_call"` + - `"1024x1024"` - The type of the item. Always `mcp_call`. + - `"1024x1536"` - - `"mcp_call"` + - `"1536x1024"` - - `agent: optional object { agent_name }` + - `"auto"` - The agent that produced this item. + - `LocalShell object { type }` - - `agent_name: string` + A tool that allows the model to execute shell commands in a local environment. - The canonical name of the agent that produced this item. + - `type: "local_shell"` - - `approval_request_id: optional string` + The type of the local shell tool. Always `local_shell`. - 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. + - `"local_shell"` - - `error: optional string` + - `Shell object { type, allowed_callers, environment }` - The error from the tool call, if any. + A tool that allows the model to execute shell commands. - - `output: optional string` + - `type: "shell"` - The output from the tool call. + The type of the shell tool. Always `shell`. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `"shell"` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"in_progress"` + The tool invocation context(s). - - `"completed"` + - `"direct"` - - `"incomplete"` + - `"programmatic"` - - `"calling"` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `"failed"` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `McpListTools object { id, server_label, tools, 3 more }` + - `BetaLocalEnvironment object { type, skills }` - A list of tools available on an MCP server. + - `BetaContainerReference object { container_id, type }` - - `id: string` + - `Custom object { name, type, allowed_callers, 3 more }` - The unique ID of the list. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `server_label: string` + - `name: string` - The label of the MCP server. + The name of the custom tool, used to identify it in tool calls. - - `tools: array of object { input_schema, name, annotations, description }` + - `type: "custom"` - The tools available on the server. + The type of the custom tool. Always `custom`. - - `input_schema: unknown` + - `"custom"` - The JSON schema describing the tool's input. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `name: string` + The tool invocation context(s). - The name of the tool. + - `"direct"` - - `annotations: optional unknown` + - `"programmatic"` - Additional annotations about the tool. + - `defer_loading: optional boolean` + + Whether this tool should be deferred and discovered via tool search. - `description: optional string` - The description of the tool. + Optional description of the custom tool, used to provide more context. - - `type: "mcp_list_tools"` + - `format: optional object { type } or object { definition, syntax, type }` - The type of the item. Always `mcp_list_tools`. + The input format for the custom tool. Default is unconstrained text. - - `"mcp_list_tools"` + - `Text object { type }` - - `agent: optional object { agent_name }` + Unconstrained free-form text. - The agent that produced this item. + - `type: "text"` - - `agent_name: string` + Unconstrained text format. Always `text`. - The canonical name of the agent that produced this item. + - `"text"` - - `error: optional string` + - `Grammar object { definition, syntax, type }` - Error message if the server could not list tools. + A grammar defined by the user. - - `McpApprovalRequest object { id, arguments, name, 3 more }` + - `definition: string` - A request for human approval of a tool invocation. + The grammar definition. - - `id: string` + - `syntax: "lark" or "regex"` - The unique ID of the approval request. + The syntax of the grammar definition. One of `lark` or `regex`. - - `arguments: string` + - `"lark"` - A JSON string of arguments for the tool. + - `"regex"` - - `name: string` + - `type: "grammar"` - The name of the tool to run. + Grammar format. Always `grammar`. - - `server_label: string` + - `"grammar"` - The label of the MCP server making the request. + - `Namespace object { description, name, tools, type }` - - `type: "mcp_approval_request"` + Groups function/custom tools under a shared namespace. - The type of the item. Always `mcp_approval_request`. + - `description: string` - - `"mcp_approval_request"` + A description of the namespace shown to the model. - - `agent: optional object { agent_name }` + - `name: string` - The agent that produced this item. + The namespace name used in tool calls (for example, `crm`). - - `agent_name: string` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - The canonical name of the agent that produced this item. + The function/custom tools available inside this namespace. - - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` + - `Function object { name, type, allowed_callers, 5 more }` - A response to an MCP approval request. + - `name: string` - - `id: string` + - `type: "function"` - The unique ID of the approval response + - `"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 should be deferred and discovered via tool search. - - `"mcp_approval_response"` + - `description: optional string` - - `agent: optional object { agent_name }` + - `output_schema: optional map[unknown]` - The agent that produced this item. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `agent_name: string` + - `parameters: optional unknown` - The canonical name of the agent that produced this item. + - `strict: optional boolean` - - `reason: optional string` + 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. - Optional reason for the decision. + - `Custom object { name, type, allowed_callers, 3 more }` - - `CustomToolCall object { call_id, input, name, 5 more }` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - A call to a custom tool created by the model. + - `name: string` - - `call_id: string` + The name of the custom tool, used to identify it in tool calls. - An identifier used to map this custom tool call to a tool call output. + - `type: "custom"` - - `input: string` + The type of the custom tool. Always `custom`. - The input for the custom tool call generated by the model. + - `"custom"` - - `name: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The name of the custom tool being called. + The tool invocation context(s). - - `type: "custom_tool_call"` + - `"direct"` - The type of the custom tool call. Always `custom_tool_call`. + - `"programmatic"` - - `"custom_tool_call"` + - `defer_loading: optional boolean` - - `id: optional string` + Whether this tool should be deferred and discovered via tool search. - The unique ID of the custom tool call in the OpenAI platform. + - `description: optional string` - - `agent: optional object { agent_name }` + Optional description of the custom tool, used to provide more context. - The agent that produced this item. + - `format: optional object { type } or object { definition, syntax, type }` - - `agent_name: string` + The input format for the custom tool. Default is unconstrained text. - The canonical name of the agent that produced this item. + - `Text object { type }` - - `caller: optional object { type } or object { caller_id, type }` + Unconstrained free-form text. - The execution context that produced this tool call. + - `type: "text"` - - `Direct object { type }` + Unconstrained text format. Always `text`. - - `type: "direct"` + - `"text"` - - `"direct"` + - `Grammar object { definition, syntax, type }` - - `Program object { caller_id, type }` + A grammar defined by the user. - - `caller_id: string` + - `definition: string` - The call ID of the program item that produced this tool call. + The grammar definition. - - `type: "program"` + - `syntax: "lark" or "regex"` - - `"program"` + The syntax of the grammar definition. One of `lark` or `regex`. - - `namespace: optional string` + - `"lark"` - The namespace of the custom tool being called. + - `"regex"` - - `CustomToolCallOutput object { id, call_id, output, 5 more }` + - `type: "grammar"` - - `id: string` + Grammar format. Always `grammar`. - The unique ID of the custom tool call output item. + - `"grammar"` - - `call_id: string` + - `type: "namespace"` - The call ID, used to map this custom tool call output to a custom tool call. + The type of the tool. Always `namespace`. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `"namespace"` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `ToolSearch object { type, description, execution, parameters }` - - `StringOutput = string` + Hosted or BYOT tool search configuration for deferred tools. - A string of the output of the custom tool call. + - `type: "tool_search"` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The type of the tool. Always `tool_search`. - Text, image, or file output of the custom tool call. + - `"tool_search"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `description: optional string` - A text input to the model. + Description shown to the model for a client-executed tool search tool. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `execution: optional "server" or "client"` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + Whether tool search is executed by the server or by the client. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `"server"` - A file input to the model. + - `"client"` - - `status: "in_progress" or "completed" or "incomplete"` + - `parameters: optional unknown` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Parameter schema for a client-executed tool search tool. - - `"in_progress"` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `"completed"` + 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). - - `"incomplete"` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `type: "custom_tool_call_output"` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The type of the custom tool call output. Always `custom_tool_call_output`. + - `"web_search_preview"` - - `"custom_tool_call_output"` + - `"web_search_preview_2025_03_11"` - - `agent: optional object { agent_name }` + - `search_content_types: optional array of "text" or "image"` - The agent that produced this item. + - `"text"` - - `agent_name: string` + - `"image"` - The canonical name of the agent that produced this item. + - `search_context_size: optional "low" or "medium" or "high"` - - `caller: optional object { type } or object { caller_id, 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. - The execution context that produced this tool call. + - `"low"` - - `Direct object { type }` + - `"medium"` - - `type: "direct"` + - `"high"` - The caller type. Always `direct`. + - `user_location: optional object { type, city, country, 2 more }` - - `"direct"` + The user's location. - - `Program object { caller_id, type }` + - `type: "approximate"` - - `caller_id: string` + The type of location approximation. Always `approximate`. - The call ID of the program item that produced this tool call. + - `"approximate"` - - `type: "program"` + - `city: optional string` - The caller type. Always `program`. + Free text input for the city of the user, e.g. `San Francisco`. - - `"program"` + - `country: optional string` - - `created_by: optional string` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The identifier of the actor that created the item. + - `region: optional string` - - `parallel_tool_calls: boolean` + Free text input for the region of the user, e.g. `California`. - Whether to allow the model to run tool calls in parallel. + - `timezone: optional string` - - `temperature: number` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - 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. + - `ApplyPatch object { type, allowed_callers }` - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + Allows the assistant to create, delete, or update files using unified diffs. - 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. + - `type: "apply_patch"` - - `BetaToolChoiceOptions = "none" or "auto" or "required"` + The type of the tool. Always `apply_patch`. - Controls which (if any) tool is called by the model. + - `"apply_patch"` - `none` means the model will not call any tool and instead generates a message. + - `allowed_callers: optional array of "direct" or "programmatic"` - `auto` means the model can pick between generating a message or calling one or - more tools. + The tool invocation context(s). - `required` means the model must call one or more tools. + - `"direct"` - - `"none"` + - `"programmatic"` - - `"auto"` + - `type: "additional_tools"` - - `"required"` + The item type. Always `additional_tools`. - - `BetaToolChoiceAllowed object { mode, tools, type }` + - `"additional_tools"` - Constrains the tools available to the model to a pre-defined set. + - `id: optional string` - - `mode: "auto" or "required"` + The unique ID of this additional tools item. - Constrains the tools available to the model to a pre-defined set. + - `agent: optional object { agent_name }` - `auto` allows the model to pick from among the allowed tools and generate a - message. + The agent that produced this item. - `required` requires the model to call one or more of the allowed tools. + - `agent_name: string` - - `"auto"` + The canonical name of the agent that produced this item. - - `"required"` + - `Reasoning object { id, summary, type, 4 more }` - - `tools: array of map[unknown]` + 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). - A list of tool definitions that the model should be allowed to call. + - `id: string` - For the Responses API, the list of tool definitions might look like: + The unique identifier of the reasoning content. - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `summary: array of object { text, type }` - - `type: "allowed_tools"` + Reasoning summary content. - Allowed tool configuration type. Always `allowed_tools`. + - `text: string` - - `"allowed_tools"` + A summary of the reasoning output from the model so far. - - `BetaToolChoiceTypes object { type }` + - `type: "summary_text"` - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](/docs/guides/tools). + The type of the object. Always `summary_text`. - - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + - `"summary_text"` - The type of hosted tool the model should to use. Learn more about - [built-in tools](/docs/guides/tools). + - `type: "reasoning"` - Allowed values are: + The type of the object. Always `reasoning`. - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `"reasoning"` - - `"file_search"` + - `agent: optional object { agent_name }` - - `"web_search_preview"` + The agent that produced this item. - - `"computer"` + - `agent_name: string` - - `"computer_use_preview"` + The canonical name of the agent that produced this item. - - `"computer_use"` + - `content: optional array of object { text, type }` - - `"web_search_preview_2025_03_11"` + Reasoning text content. - - `"image_generation"` + - `text: string` - - `"code_interpreter"` + The reasoning text from the model. - - `BetaToolChoiceFunction object { name, type }` + - `type: "reasoning_text"` - Use this option to force the model to call a specific function. + The type of the reasoning text. Always `reasoning_text`. - - `name: string` + - `"reasoning_text"` - The name of the function to call. + - `encrypted_content: optional string` - - `type: "function"` + 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. - For function calling, the type is always `function`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"function"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `BetaToolChoiceMcp object { server_label, type, name }` + - `"in_progress"` - Use this option to force the model to call a specific tool on a remote MCP server. + - `"completed"` - - `server_label: string` + - `"incomplete"` - The label of the MCP server to use. + - `Compaction object { encrypted_content, type, id, agent }` - - `type: "mcp"` + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - For MCP tools, the type is always `mcp`. + - `encrypted_content: string` - - `"mcp"` + The encrypted content of the compaction summary. - - `name: optional string` + - `type: "compaction"` - The name of the tool to call on the server. + The type of the item. Always `compaction`. - - `BetaToolChoiceCustom object { name, type }` + - `"compaction"` - Use this option to force the model to call a specific custom tool. + - `id: optional string` - - `name: string` + The ID of the compaction item. - The name of the custom tool to call. + - `agent: optional object { agent_name }` - - `type: "custom"` + The agent that produced this item. - For custom tool calling, the type is always `custom`. + - `agent_name: string` - - `"custom"` + The canonical name of the agent that produced this item. - - `BetaSpecificProgrammaticToolCallingParam object { type }` + - `ImageGenerationCall object { id, result, status, 2 more }` - - `type: "programmatic_tool_calling"` + An image generation request made by the model. - The tool to call. Always `programmatic_tool_calling`. + - `id: string` - - `"programmatic_tool_calling"` + The unique ID of the image generation call. - - `BetaToolChoiceApplyPatch object { type }` + - `result: string` - Forces the model to call the apply_patch tool when executing a tool call. + The generated image encoded in base64. - - `type: "apply_patch"` + - `status: "in_progress" or "completed" or "generating" or "failed"` - The tool to call. Always `apply_patch`. + The status of the image generation call. - - `"apply_patch"` + - `"in_progress"` - - `BetaToolChoiceShell object { type }` + - `"completed"` - Forces the model to call the shell tool when a tool call is required. + - `"generating"` - - `type: "shell"` + - `"failed"` - The tool to call. Always `shell`. + - `type: "image_generation_call"` - - `"shell"` + The type of the image generation call. Always `image_generation_call`. - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + - `"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. + - `agent: optional object { agent_name }` - We support the following categories of tools: + The agent that produced this item. - - **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. + - `agent_name: string` - - `Function object { name, parameters, strict, 5 more }` + The canonical name of the agent that produced this item. - 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). + - `CodeInterpreterCall object { id, code, container_id, 4 more }` - - `name: string` + A tool call to run code. - The name of the function to call. + - `id: string` - - `parameters: map[unknown]` + The unique ID of the code interpreter tool call. - A JSON schema object describing the parameters of the function. + - `code: string` - - `strict: boolean` + The code to run, or null if not available. - Whether strict parameter validation is enforced for this function tool. + - `container_id: string` - - `type: "function"` + The ID of the container used to run the code. - The type of the function tool. Always `function`. + - `outputs: array of object { logs, type } or object { type, url }` - - `"function"` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `Logs object { logs, type }` - The tool invocation context(s). + The logs output from the code interpreter. - - `"direct"` + - `logs: string` - - `"programmatic"` + The logs output from the code interpreter. - - `defer_loading: optional boolean` + - `type: "logs"` - Whether this function is deferred and loaded via tool search. + The type of the output. Always `logs`. - - `description: optional string` + - `"logs"` - A description of the function. Used by the model to determine whether or not to call the function. + - `Image object { type, url }` - - `output_schema: optional map[unknown]` + The image output from the code interpreter. - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `type: "image"` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + The type of the output. Always `image`. - 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). + - `"image"` - - `type: "file_search"` + - `url: string` - The type of the file search tool. Always `file_search`. + The URL of the image output from the code interpreter. - - `"file_search"` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - `vector_store_ids: array of string` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - The IDs of the vector stores to search. + - `"in_progress"` - - `filters: optional object { key, type, value } or object { filters, type }` + - `"completed"` - A filter to apply. + - `"incomplete"` - - `ComparisonFilter object { key, type, value }` + - `"interpreting"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"failed"` - - `key: string` + - `type: "code_interpreter_call"` - The key to compare against the value. + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `type: "eq" or "ne" or "gt" or 5 more` + - `"code_interpreter_call"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `agent: optional object { agent_name }` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + The agent that produced this item. - - `"eq"` + - `agent_name: string` - - `"ne"` + The canonical name of the agent that produced this item. - - `"gt"` + - `LocalShellCall object { id, action, call_id, 3 more }` - - `"gte"` + A tool call to run a command on the local shell. - - `"lt"` + - `id: string` - - `"lte"` + The unique ID of the local shell call. - - `"in"` + - `action: object { command, env, type, 3 more }` - - `"nin"` + Execute a shell command on the server. - - `value: string or number or boolean or array of string or number` + - `command: array of string` - The value to compare against the attribute key; supports string, number, or boolean types. + The command to run. - - `string` + - `env: map[string]` - - `number` + Environment variables to set for the command. - - `boolean` + - `type: "exec"` - - `array of string or number` + The type of the local shell action. Always `exec`. - - `string` + - `"exec"` - - `number` + - `timeout_ms: optional number` - - `CompoundFilter object { filters, type }` + Optional timeout in milliseconds for the command. - Combine multiple filters using `and` or `or`. + - `user: optional string` - - `filters: array of object { key, type, value } or unknown` + Optional user to run the command as. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `working_directory: optional string` - - `ComparisonFilter object { key, type, value }` + Optional working directory to run the command in. - 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 local shell tool call generated by the model. - The key to compare against the value. + - `status: "in_progress" or "completed" or "incomplete"` - - `type: "eq" or "ne" or "gt" or 5 more` + The status of the local shell call. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"in_progress"` - - `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 + - `"completed"` - - `"eq"` + - `"incomplete"` - - `"ne"` + - `type: "local_shell_call"` - - `"gt"` + The type of the local shell call. Always `local_shell_call`. - - `"gte"` + - `"local_shell_call"` - - `"lt"` + - `agent: optional object { agent_name }` - - `"lte"` + The agent that produced this item. - - `"in"` + - `agent_name: string` - - `"nin"` + The canonical name of the agent that produced this item. - - `value: string or number or boolean or array of string or number` + - `LocalShellCallOutput object { id, output, type, 2 more }` - The value to compare against the attribute key; supports string, number, or boolean types. + The output of a local shell tool call. - - `string` + - `id: string` - - `number` + The unique ID of the local shell tool call generated by the model. - - `boolean` + - `output: string` - - `array of string or number` + A JSON string of the output of the local shell tool call. - - `string` + - `type: "local_shell_call_output"` - - `number` + The type of the local shell tool call output. Always `local_shell_call_output`. - - `unknown` + - `"local_shell_call_output"` - - `type: "and" or "or"` + - `agent: optional object { agent_name }` - Type of operation: `and` or `or`. + The agent that produced this item. - - `"and"` + - `agent_name: string` - - `"or"` + The canonical name of the agent that produced this item. - - `max_num_results: optional number` + - `status: optional "in_progress" or "completed" or "incomplete"` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `"in_progress"` - Ranking options for search. + - `"completed"` - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `"incomplete"` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `ShellCall object { action, call_id, type, 5 more }` - - `embedding_weight: number` + A tool representing a request to execute one or more shell commands. - The weight of the embedding in the reciprocal ranking fusion. + - `action: object { commands, max_output_length, timeout_ms }` - - `text_weight: number` + The shell commands and limits that describe how to run the tool call. - The weight of the text in the reciprocal ranking fusion. + - `commands: array of string` - - `ranker: optional "auto" or "default-2024-11-15"` + Ordered shell commands for the execution environment to run. - The ranker to use for the file search. + - `max_output_length: optional number` - - `"auto"` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `"default-2024-11-15"` + - `timeout_ms: optional number` - - `score_threshold: optional number` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - 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. + - `call_id: string` - - `Computer object { type }` + The unique ID of the shell tool call generated by the model. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `type: "shell_call"` - - `type: "computer"` + The type of the item. Always `shell_call`. - The type of the computer tool. Always `computer`. + - `"shell_call"` - - `"computer"` + - `id: optional string` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + The unique ID of the shell tool call. Populated when this item is returned via API. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `agent: optional object { agent_name }` - - `display_height: number` + The agent that produced this item. - The height of the computer display. + - `agent_name: string` - - `display_width: number` + The canonical name of the agent that produced this item. - The width of the computer display. + - `caller: optional object { type } or object { caller_id, type }` - - `environment: "windows" or "mac" or "linux" or 2 more` + The execution context that produced this tool call. - The type of computer environment to control. + - `Direct object { type }` - - `"windows"` + - `type: "direct"` - - `"mac"` + The caller type. Always `direct`. - - `"linux"` + - `"direct"` - - `"ubuntu"` + - `Program object { caller_id, type }` - - `"browser"` + - `caller_id: string` - - `type: "computer_use_preview"` + The call ID of the program item that produced this tool call. - The type of the computer use tool. Always `computer_use_preview`. + - `type: "program"` - - `"computer_use_preview"` + The caller type. Always `program`. - - `WebSearch object { type, filters, search_context_size, user_location }` + - `"program"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + - `environment: optional BetaLocalEnvironment or BetaContainerReference` - - `type: "web_search" or "web_search_2025_08_26"` + The environment to execute the shell commands in. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `BetaLocalEnvironment object { type, skills }` - - `"web_search"` + - `BetaContainerReference object { container_id, type }` - - `"web_search_2025_08_26"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `filters: optional object { allowed_domains }` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - Filters for the search. + - `"in_progress"` - - `allowed_domains: optional array of string` + - `"completed"` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `"incomplete"` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `ShellCallOutput object { call_id, output, type, 5 more }` - - `search_context_size: optional "low" or "medium" or "high"` + The streamed output items emitted by a shell 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. + - `call_id: string` - - `"low"` + The unique ID of the shell tool call generated by the model. - - `"medium"` + - `output: array of BetaResponseFunctionShellCallOutputContent` - - `"high"` + Captured chunks of stdout and stderr output, along with their associated outcomes. - - `user_location: optional object { city, country, region, 2 more }` + - `outcome: object { type } or object { exit_code, type }` - The approximate location of the user. + The exit or timeout outcome associated with this shell call. - - `city: optional string` + - `Timeout object { type }` - Free text input for the city of the user, e.g. `San Francisco`. + Indicates that the shell call exceeded its configured time limit. - - `country: optional string` + - `type: "timeout"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The outcome type. Always `timeout`. - - `region: optional string` + - `"timeout"` - Free text input for the region of the user, e.g. `California`. + - `Exit object { exit_code, type }` - - `timezone: optional string` + Indicates that the shell commands finished and returned an exit code. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `exit_code: number` - - `type: optional "approximate"` + The exit code returned by the shell process. - The type of location approximation. Always `approximate`. + - `type: "exit"` - - `"approximate"` + The outcome type. Always `exit`. - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `"exit"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + - `stderr: string` - - `server_label: string` + Captured stderr output for the shell call. - A label for this MCP server, used to identify it in tool calls. + - `stdout: string` - - `type: "mcp"` + Captured stdout output for the shell call. - The type of the MCP tool. Always `mcp`. + - `type: "shell_call_output"` - - `"mcp"` + The type of the item. Always `shell_call_output`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"shell_call_output"` - The tool invocation context(s). + - `id: optional string` - - `"direct"` + The unique ID of the shell tool call output. Populated when this item is returned via API. - - `"programmatic"` + - `agent: optional object { agent_name }` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + The agent that produced this item. - List of allowed tool names or a filter object. + - `agent_name: string` - - `McpAllowedTools = array of string` + The canonical name of the agent that produced this item. - A string array of allowed tool names + - `caller: optional object { type } or object { caller_id, type }` - - `McpToolFilter object { read_only, tool_names }` + The execution context that produced this tool call. - A filter object to specify which tools are allowed. + - `Direct object { type }` - - `read_only: optional boolean` + - `type: "direct"` - 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 caller type. Always `direct`. - - `tool_names: optional array of string` + - `"direct"` - List of allowed tool names. + - `Program object { caller_id, type }` - - `authorization: optional string` + - `caller_id: string` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + The call ID of the program item that produced this tool call. - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `type: "program"` - 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 caller type. Always `program`. - Currently supported `connector_id` values are: + - `"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` + - `max_output_length: optional number` - - `"connector_dropbox"` + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `"connector_gmail"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"connector_googlecalendar"` + The status of the shell call output. - - `"connector_googledrive"` + - `"in_progress"` - - `"connector_microsoftteams"` + - `"completed"` - - `"connector_outlookcalendar"` + - `"incomplete"` - - `"connector_outlookemail"` + - `ApplyPatchCall object { call_id, operation, status, 4 more }` - - `"connector_sharepoint"` + A tool call representing a request to create, delete, or update files using diff patches. - - `defer_loading: optional boolean` + - `call_id: string` - Whether this MCP tool is deferred and discovered via tool search. + The unique ID of the apply patch tool call generated by the model. - - `headers: optional map[string]` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The specific create, delete, or update instruction for the apply_patch tool call. - - `require_approval: optional object { always, never } or "always" or "never"` + - `CreateFile object { diff, path, type }` - Specify which of the MCP server's tools require approval. + Instruction for creating a new file via the apply_patch tool. - - `McpToolApprovalFilter object { always, never }` + - `diff: 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. + Unified diff content to apply when creating the file. - - `always: optional object { read_only, tool_names }` + - `path: string` - A filter object to specify which tools are allowed. + Path of the file to create relative to the workspace root. - - `read_only: optional boolean` + - `type: "create_file"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The operation type. Always `create_file`. - - `tool_names: optional array of string` + - `"create_file"` - List of allowed tool names. + - `DeleteFile object { path, type }` - - `never: optional object { read_only, tool_names }` + Instruction for deleting an existing file via the apply_patch tool. - A filter object to specify which tools are allowed. + - `path: string` - - `read_only: optional boolean` + Path of the file to delete relative to the workspace root. - 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: "delete_file"` - - `tool_names: optional array of string` + The operation type. Always `delete_file`. - List of allowed tool names. + - `"delete_file"` - - `McpToolApprovalSetting = "always" or "never"` + - `UpdateFile object { diff, path, 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. + Instruction for updating an existing file via the apply_patch tool. - - `"always"` + - `diff: string` - - `"never"` + Unified diff content to apply to the existing file. - - `server_description: optional string` + - `path: string` - Optional description of the MCP server, used to provide more context. + Path of the file to update relative to the workspace root. - - `server_url: optional string` + - `type: "update_file"` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + The operation type. Always `update_file`. - - `tunnel_id: optional string` + - `"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. + - `status: "in_progress" or "completed"` - - `CodeInterpreter object { container, type, allowed_callers }` + The status of the apply patch tool call. One of `in_progress` or `completed`. - A tool that runs Python code to help generate a response to a prompt. + - `"in_progress"` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `"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. + - `type: "apply_patch_call"` - - `string` + The type of the item. Always `apply_patch_call`. - The container ID. + - `"apply_patch_call"` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `id: optional string` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `type: "auto"` + - `agent: optional object { agent_name }` - Always `auto`. + The agent that produced this item. - - `"auto"` + - `agent_name: string` - - `file_ids: optional array of string` + The canonical name of the agent that produced this item. - An optional list of uploaded files to make available to your code. + - `caller: optional object { type } or object { caller_id, type }` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + The execution context that produced this tool call. - The memory limit for the code interpreter container. + - `Direct object { type }` - - `"1g"` + - `type: "direct"` - - `"4g"` + The caller type. Always `direct`. - - `"16g"` + - `"direct"` - - `"64g"` + - `Program object { caller_id, type }` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `caller_id: string` - Network access policy for the container. + The call ID of the program item that produced this tool call. - - `BetaContainerNetworkPolicyDisabled object { type }` + - `type: "program"` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + The caller type. Always `program`. - - `type: "code_interpreter"` + - `"program"` - The type of the code interpreter tool. Always `code_interpreter`. + - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` - - `"code_interpreter"` + The streamed output emitted by an apply patch tool call. - - `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`. - - `ProgrammaticToolCalling object { type }` + - `"completed"` - - `type: "programmatic_tool_calling"` + - `"failed"` - The type of the tool. Always `programmatic_tool_calling`. + - `type: "apply_patch_call_output"` - - `"programmatic_tool_calling"` + The type of the item. Always `apply_patch_call_output`. - - `ImageGeneration object { type, action, background, 9 more }` + - `"apply_patch_call_output"` - A tool that generates images using the GPT image models. + - `id: optional string` - - `type: "image_generation"` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - The type of the image generation tool. Always `image_generation`. + - `agent: optional object { agent_name }` - - `"image_generation"` + The agent that produced this item. - - `action: optional "generate" or "edit" or "auto"` + - `agent_name: string` - Whether to generate a new image or edit an existing image. Default: `auto`. + The canonical name of the agent that produced this item. - - `"generate"` + - `caller: optional object { type } or object { caller_id, type }` - - `"edit"` + The execution context that produced this tool call. - - `"auto"` + - `Direct object { type }` - - `background: optional "transparent" or "opaque" or "auto"` + - `type: "direct"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + The caller type. Always `direct`. - - `"transparent"` + - `"direct"` - - `"opaque"` + - `Program object { caller_id, type }` - - `"auto"` + - `caller_id: string` - - `input_fidelity: optional "high" or "low"` + The call ID of the program item that produced this tool call. - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + - `type: "program"` - - `"high"` + The caller type. Always `program`. - - `"low"` + - `"program"` - - `input_image_mask: optional object { file_id, image_url }` + - `output: optional string` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - `file_id: optional string` + - `McpListTools object { id, server_label, tools, 3 more }` - File ID for the mask image. + A list of tools available on an MCP server. - - `image_url: optional string` + - `id: string` - Base64-encoded mask image. + The unique ID of the list. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `server_label: string` - The image generation model to use. Default: `gpt-image-1`. + The label of the MCP server. - - `string` + - `tools: array of object { input_schema, name, annotations, description }` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + The tools available on the server. - The image generation model to use. Default: `gpt-image-1`. + - `input_schema: unknown` - - `"gpt-image-1"` + The JSON schema describing the tool's input. - - `"gpt-image-1-mini"` + - `name: string` - - `"gpt-image-1.5"` + The name of the tool. - - `moderation: optional "auto" or "low"` + - `annotations: optional unknown` - Moderation level for the generated image. Default: `auto`. + Additional annotations about the tool. - - `"auto"` + - `description: optional string` - - `"low"` + The description of the tool. - - `output_compression: optional number` + - `type: "mcp_list_tools"` - Compression level for the output image. Default: 100. + The type of the item. Always `mcp_list_tools`. - - `output_format: optional "png" or "webp" or "jpeg"` + - `"mcp_list_tools"` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `agent: optional object { agent_name }` - - `"png"` + The agent that produced this item. - - `"webp"` + - `agent_name: string` - - `"jpeg"` + The canonical name of the agent that produced this item. - - `partial_images: optional number` + - `error: optional string` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + Error message if the server could not list tools. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `McpApprovalRequest object { id, arguments, name, 3 more }` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + A request for human approval of a tool invocation. - - `"low"` + - `id: string` - - `"medium"` + The unique ID of the approval request. - - `"high"` + - `arguments: string` - - `"auto"` + A JSON string of arguments for the tool. - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `name: string` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + The name of the tool to run. - - `string` + - `server_label: string` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The label of the MCP server making the request. - 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: "mcp_approval_request"` - - `"1024x1024"` + The type of the item. Always `mcp_approval_request`. - - `"1024x1536"` + - `"mcp_approval_request"` - - `"1536x1024"` + - `agent: optional object { agent_name }` - - `"auto"` + The agent that produced this item. - - `LocalShell object { type }` + - `agent_name: string` - A tool that allows the model to execute shell commands in a local environment. + The canonical name of the agent that produced this item. - - `type: "local_shell"` + - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` - The type of the local shell tool. Always `local_shell`. + A response to an MCP approval request. - - `"local_shell"` + - `approval_request_id: string` - - `Shell object { type, allowed_callers, environment }` + The ID of the approval request being answered. - A tool that allows the model to execute shell commands. + - `approve: boolean` - - `type: "shell"` + Whether the request was approved. - The type of the shell tool. Always `shell`. + - `type: "mcp_approval_response"` - - `"shell"` + The type of the item. Always `mcp_approval_response`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"mcp_approval_response"` - The tool invocation context(s). + - `id: optional string` - - `"direct"` + The unique ID of the approval response - - `"programmatic"` + - `agent: optional object { agent_name }` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + The agent that produced this item. - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `agent_name: string` - - `BetaLocalEnvironment object { type, skills }` + The canonical name of the agent that produced this item. - - `BetaContainerReference object { container_id, type }` + - `reason: optional string` - - `Custom object { name, type, allowed_callers, 3 more }` + Optional reason for the decision. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `McpCall object { id, arguments, name, 7 more }` - - `name: string` + An invocation of a tool on an MCP server. - The name of the custom tool, used to identify it in tool calls. + - `id: string` - - `type: "custom"` + The unique ID of the tool call. - The type of the custom tool. Always `custom`. + - `arguments: string` - - `"custom"` + A JSON string of the arguments passed to the tool. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `name: string` - The tool invocation context(s). + The name of the tool that was run. - - `"direct"` + - `server_label: string` - - `"programmatic"` + The label of the MCP server running the tool. - - `defer_loading: optional boolean` + - `type: "mcp_call"` - Whether this tool should be deferred and discovered via tool search. + The type of the item. Always `mcp_call`. - - `description: optional string` + - `"mcp_call"` - Optional description of the custom tool, used to provide more context. + - `agent: optional object { agent_name }` - - `format: optional object { type } or object { definition, syntax, type }` + The agent that produced this item. - The input format for the custom tool. Default is unconstrained text. + - `agent_name: string` - - `Text object { type }` + The canonical name of the agent that produced this item. - Unconstrained free-form text. + - `approval_request_id: optional string` - - `type: "text"` + 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. - Unconstrained text format. Always `text`. + - `error: optional string` - - `"text"` + The error from the tool call, if any. - - `Grammar object { definition, syntax, type }` + - `output: optional string` - A grammar defined by the user. + The output from the tool call. - - `definition: string` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - The grammar definition. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `syntax: "lark" or "regex"` + - `"in_progress"` - The syntax of the grammar definition. One of `lark` or `regex`. + - `"completed"` - - `"lark"` + - `"incomplete"` - - `"regex"` + - `"calling"` - - `type: "grammar"` + - `"failed"` - Grammar format. Always `grammar`. + - `CustomToolCallOutput object { call_id, output, type, 3 more }` - - `"grammar"` + The output of a custom tool call from your code, being sent back to the model. - - `Namespace object { description, name, tools, type }` + - `call_id: string` - Groups function/custom tools under a shared namespace. + The call ID, used to map this custom tool call output to a custom tool call. - - `description: string` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - A description of the namespace shown to the model. + 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 namespace name used in tool calls (for example, `crm`). + A string of the output of the custom tool call. - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The function/custom tools available inside this namespace. + Text, image, or file output of the custom tool call. - - `Function object { name, type, allowed_callers, 5 more }` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `name: string` + A text input to the model. - - `type: "function"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `"function"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `allowed_callers: optional array of "direct" or "programmatic"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - The tool invocation context(s). + A file input to the model. - - `"direct"` + - `type: "custom_tool_call_output"` - - `"programmatic"` + The type of the custom tool call output. Always `custom_tool_call_output`. - - `defer_loading: optional boolean` + - `"custom_tool_call_output"` - Whether this function should be deferred and discovered via tool search. + - `id: optional string` - - `description: optional string` + The unique ID of the custom tool call output in the OpenAI platform. - - `output_schema: optional map[unknown]` + - `agent: optional object { agent_name }` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + The agent that produced this item. - - `parameters: optional unknown` + - `agent_name: string` - - `strict: optional boolean` + The canonical name of the agent that produced this 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. + - `caller: optional object { type } or object { caller_id, type }` - - `Custom object { name, type, allowed_callers, 3 more }` + The execution context that produced this tool call. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `Direct object { type }` - - `name: string` + - `type: "direct"` - The name of the custom tool, used to identify it in tool calls. + The caller type. Always `direct`. - - `type: "custom"` + - `"direct"` - The type of the custom tool. Always `custom`. + - `Program object { caller_id, type }` - - `"custom"` + - `caller_id: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The call ID of the program item that produced this tool call. - The tool invocation context(s). + - `type: "program"` - - `"direct"` + The caller type. Always `program`. - - `"programmatic"` + - `"program"` - - `defer_loading: optional boolean` + - `CustomToolCall object { call_id, input, name, 5 more }` - Whether this tool should be deferred and discovered via tool search. + A call to a custom tool created by the model. - - `description: optional string` + - `call_id: string` - Optional description of the custom tool, used to provide more context. + An identifier used to map this custom tool call to a tool call output. - - `format: optional object { type } or object { definition, syntax, type }` + - `input: string` - The input format for the custom tool. Default is unconstrained text. + The input for the custom tool call generated by the model. - - `Text object { type }` + - `name: string` - Unconstrained free-form text. + The name of the custom tool being called. - - `type: "text"` + - `type: "custom_tool_call"` - Unconstrained text format. Always `text`. + The type of the custom tool call. Always `custom_tool_call`. - - `"text"` + - `"custom_tool_call"` - - `Grammar object { definition, syntax, type }` + - `id: optional string` - A grammar defined by the user. + The unique ID of the custom tool call in the OpenAI platform. - - `definition: string` + - `agent: optional object { agent_name }` - The grammar definition. + The agent that produced this item. - - `syntax: "lark" or "regex"` + - `agent_name: string` - The syntax of the grammar definition. One of `lark` or `regex`. + The canonical name of the agent that produced this item. - - `"lark"` + - `caller: optional object { type } or object { caller_id, type }` - - `"regex"` + The execution context that produced this tool call. - - `type: "grammar"` + - `Direct object { type }` - Grammar format. Always `grammar`. + - `type: "direct"` - - `"grammar"` + - `"direct"` - - `type: "namespace"` + - `Program object { caller_id, type }` - The type of the tool. Always `namespace`. + - `caller_id: string` - - `"namespace"` + The call ID of the program item that produced this tool call. - - `ToolSearch object { type, description, execution, parameters }` + - `type: "program"` - Hosted or BYOT tool search configuration for deferred tools. + - `"program"` - - `type: "tool_search"` + - `namespace: optional string` - The type of the tool. Always `tool_search`. + The namespace of the custom tool being called. - - `"tool_search"` + - `CompactionTrigger object { type, agent }` - - `description: optional string` + Compacts the current context. Must be the final input item. - Description shown to the model for a client-executed tool search tool. + - `type: "compaction_trigger"` - - `execution: optional "server" or "client"` + The type of the item. Always `compaction_trigger`. - Whether tool search is executed by the server or by the client. + - `"compaction_trigger"` - - `"server"` + - `agent: optional object { agent_name }` - - `"client"` + The agent that produced this item. - - `parameters: optional unknown` + - `agent_name: string` - Parameter schema for a client-executed tool search tool. + The canonical name of the agent that produced this item. - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `ItemReference object { id, agent, 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). + An internal identifier for an item to reference. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `id: string` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + The ID of the item to reference. - - `"web_search_preview"` + - `agent: optional object { agent_name }` - - `"web_search_preview_2025_03_11"` + The agent that produced this item. - - `search_content_types: optional array of "text" or "image"` + - `agent_name: string` - - `"text"` + The canonical name of the agent that produced this item. - - `"image"` + - `type: optional "item_reference"` - - `search_context_size: optional "low" or "medium" or "high"` + The type of item to reference. Always `item_reference`. - 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. + - `"item_reference"` - - `"low"` + - `Program object { id, call_id, code, 3 more }` - - `"medium"` + - `id: string` - - `"high"` + The unique ID of this program item. - - `user_location: optional object { type, city, country, 2 more }` + - `call_id: string` - The user's location. + The stable call ID of the program item. - - `type: "approximate"` + - `code: string` - The type of location approximation. Always `approximate`. + The JavaScript source executed by programmatic tool calling. - - `"approximate"` + - `fingerprint: string` - - `city: optional string` + Opaque program replay fingerprint that must be round-tripped. - Free text input for the city of the user, e.g. `San Francisco`. + - `type: "program"` - - `country: optional string` + The item type. Always `program`. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `"program"` - - `region: optional string` + - `agent: optional object { agent_name }` - Free text input for the region of the user, e.g. `California`. + The agent that produced this item. - - `timezone: optional string` + - `agent_name: string` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The canonical name of the agent that produced this item. - - `ApplyPatch object { type, allowed_callers }` + - `ProgramOutput object { id, call_id, result, 3 more }` - Allows the assistant to create, delete, or update files using unified diffs. + - `id: string` - - `type: "apply_patch"` + The unique ID of this program output item. - The type of the tool. Always `apply_patch`. + - `call_id: string` - - `"apply_patch"` + The call ID of the program item. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `result: string` - The tool invocation context(s). + The result produced by the program item. - - `"direct"` + - `status: "completed" or "incomplete"` - - `"programmatic"` + The terminal status of the program output. - - `top_p: number` + - `"completed"` - 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. + - `"incomplete"` - We generally recommend altering this or `temperature` but not both. + - `type: "program_output"` - - `background: optional boolean` + The item type. Always `program_output`. - Whether to run the model response in the background. - [Learn more](/docs/guides/background). + - `"program_output"` - - `completed_at: optional number` + - `agent: optional object { agent_name }` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + The agent that produced this item. - - `conversation: optional object { id }` + - `agent_name: string` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + The canonical name of the agent that produced this item. - - `id: string` + - `metadata: map[string]` - The unique ID of the conversation that this response was associated with. + 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. - - `max_output_tokens: optional number` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - 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). + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - - `max_tool_calls: optional number` + 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. - 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. + - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` - - `moderation: optional object { input, output }` + 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. - Moderation results for the response input and output, if moderated completions were requested. + - `"gpt-5.6-sol"` - - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + - `"gpt-5.6-terra"` - Moderation for the response input. + - `"gpt-5.6-luna"` - - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + - `"gpt-5.4"` - A moderation result produced for the response input or output. + - `"gpt-5.4-mini"` - - `categories: map[boolean]` + - `"gpt-5.4-nano"` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `"gpt-5.4-mini-2026-03-17"` - - `category_applied_input_types: map[array of "text" or "image"]` + - `"gpt-5.4-nano-2026-03-17"` - Which modalities of input are reflected by the score for each category. + - `"gpt-5.3-chat-latest"` - - `"text"` + - `"gpt-5.2"` - - `"image"` + - `"gpt-5.2-2025-12-11"` - - `category_scores: map[number]` + - `"gpt-5.2-chat-latest"` - A dictionary of moderation categories to scores. + - `"gpt-5.2-pro"` - - `flagged: boolean` + - `"gpt-5.2-pro-2025-12-11"` - A boolean indicating whether the content was flagged by any category. + - `"gpt-5.1"` - - `model: string` + - `"gpt-5.1-2025-11-13"` - The moderation model that produced this result. + - `"gpt-5.1-codex"` - - `type: "moderation_result"` + - `"gpt-5.1-mini"` - The object type, which was always `moderation_result` for successful moderation results. + - `"gpt-5.1-chat-latest"` - - `"moderation_result"` + - `"gpt-5"` - - `Error object { code, message, type }` + - `"gpt-5-mini"` - An error produced while attempting moderation for the response input or output. + - `"gpt-5-nano"` - - `code: string` + - `"gpt-5-2025-08-07"` - The error code. + - `"gpt-5-mini-2025-08-07"` - - `message: string` + - `"gpt-5-nano-2025-08-07"` - The error message. + - `"gpt-5-chat-latest"` - - `type: "error"` + - `"gpt-4.1"` - The object type, which was always `error` for moderation failures. + - `"gpt-4.1-mini"` - - `"error"` + - `"gpt-4.1-nano"` - - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + - `"gpt-4.1-2025-04-14"` - Moderation for the response output. + - `"gpt-4.1-mini-2025-04-14"` - - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + - `"gpt-4.1-nano-2025-04-14"` - A moderation result produced for the response input or output. + - `"o4-mini"` - - `categories: map[boolean]` + - `"o4-mini-2025-04-16"` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `"o3"` - - `category_applied_input_types: map[array of "text" or "image"]` + - `"o3-2025-04-16"` - Which modalities of input are reflected by the score for each category. + - `"o3-mini"` - - `"text"` + - `"o3-mini-2025-01-31"` - - `"image"` + - `"o1"` - - `category_scores: map[number]` + - `"o1-2024-12-17"` - A dictionary of moderation categories to scores. + - `"o1-preview"` - - `flagged: boolean` + - `"o1-preview-2024-09-12"` - A boolean indicating whether the content was flagged by any category. + - `"o1-mini"` - - `model: string` + - `"o1-mini-2024-09-12"` - The moderation model that produced this result. + - `"gpt-4o"` - - `type: "moderation_result"` + - `"gpt-4o-2024-11-20"` - The object type, which was always `moderation_result` for successful moderation results. + - `"gpt-4o-2024-08-06"` - - `"moderation_result"` + - `"gpt-4o-2024-05-13"` - - `Error object { code, message, type }` + - `"gpt-4o-audio-preview"` - An error produced while attempting moderation for the response input or output. + - `"gpt-4o-audio-preview-2024-10-01"` - - `code: string` + - `"gpt-4o-audio-preview-2024-12-17"` - The error code. + - `"gpt-4o-audio-preview-2025-06-03"` - - `message: string` + - `"gpt-4o-mini-audio-preview"` - The error message. + - `"gpt-4o-mini-audio-preview-2024-12-17"` - - `type: "error"` + - `"gpt-4o-search-preview"` - The object type, which was always `error` for moderation failures. + - `"gpt-4o-mini-search-preview"` - - `"error"` + - `"gpt-4o-search-preview-2025-03-11"` - - `output_text: optional string` + - `"gpt-4o-mini-search-preview-2025-03-11"` - 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. + - `"chatgpt-4o-latest"` - - `previous_response_id: optional string` + - `"codex-mini-latest"` - 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`. + - `"gpt-4o-mini"` - - `prompt: optional BetaResponsePrompt` + - `"gpt-4o-mini-2024-07-18"` - Reference to a prompt template and its variables. - [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). + - `"gpt-4-turbo"` - - `id: string` + - `"gpt-4-turbo-2024-04-09"` - The unique identifier of the prompt template to use. + - `"gpt-4-0125-preview"` - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + - `"gpt-4-turbo-preview"` - 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. + - `"gpt-4-1106-preview"` - - `string` + - `"gpt-4-vision-preview"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `"gpt-4"` - A text input to the model. + - `"gpt-4-0314"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `"gpt-4-0613"` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `"gpt-4-32k"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `"gpt-4-32k-0314"` - A file input to the model. + - `"gpt-4-32k-0613"` - - `version: optional string` + - `"gpt-3.5-turbo"` - Optional version of the prompt template. + - `"gpt-3.5-turbo-16k"` - - `prompt_cache_key: optional string` + - `"gpt-3.5-turbo-0301"` - 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). + - `"gpt-3.5-turbo-0613"` - - `prompt_cache_options: optional object { mode, ttl }` + - `"gpt-3.5-turbo-1106"` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `"gpt-3.5-turbo-0125"` - - `mode: "implicit" or "explicit"` + - `"gpt-3.5-turbo-16k-0613"` - Whether implicit prompt-cache breakpoints were enabled. + - `"o1-pro"` - - `"implicit"` + - `"o1-pro-2025-03-19"` - - `"explicit"` + - `"o3-pro"` - - `ttl: "30m"` + - `"o3-pro-2025-06-10"` - The minimum lifetime applied to each cache breakpoint. + - `"o3-deep-research"` - - `"30m"` + - `"o3-deep-research-2025-06-26"` - - `prompt_cache_retention: optional "in_memory" or "24h"` + - `"o4-mini-deep-research"` - Deprecated. Use `prompt_cache_options.ttl` instead. + - `"o4-mini-deep-research-2025-06-26"` - 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. + - `"computer-use-preview"` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `"computer-use-preview-2025-03-11"` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `"gpt-5-codex"` - - `"in_memory"` + - `"gpt-5-pro"` - - `"24h"` + - `"gpt-5-pro-2025-10-06"` - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + - `"gpt-5.1-codex-max"` - **gpt-5 and o-series models only** + - `string` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `object: "response"` - - `context: optional "auto" or "current_turn" or "all_turns"` + The object type of this resource - always set to `response`. - 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`. + - `"response"` - When returned on a response, this is the effective reasoning context mode - used for the response. + - `output: array of BetaResponseOutputItem` - - `"auto"` + An array of content items generated by the model. - - `"current_turn"` + - 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. - - `"all_turns"` + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - - `effort: optional "none" or "minimal" or "low" or 4 more` + An output message from the model. - 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. + - `FileSearchCall object { id, queries, status, 3 more }` - - `"none"` + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - - `"minimal"` + - `id: string` - - `"low"` + The unique ID of the file search tool call. - - `"medium"` + - `queries: array of string` - - `"high"` + The queries used to search for files. - - `"xhigh"` + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `"max"` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `generate_summary: optional "auto" or "concise" or "detailed"` + - `"in_progress"` - **Deprecated:** use `summary` instead. + - `"searching"` - 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`. + - `"completed"` - - `"auto"` + - `"incomplete"` - - `"concise"` + - `"failed"` - - `"detailed"` + - `type: "file_search_call"` - - `mode: optional string or "standard" or "pro"` + The type of the file search tool call. Always `file_search_call`. - Controls the reasoning execution mode for the request. + - `"file_search_call"` - When returned on a response, this is the effective execution mode. + - `agent: optional object { agent_name }` - - `string` + The agent that produced this item. - - `"standard" or "pro"` + - `agent_name: string` - Controls the reasoning execution mode for the request. + The canonical name of the agent that produced this item. - When returned on a response, this is the effective execution mode. + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `"standard"` + The results of the file search tool call. - - `"pro"` + - `attributes: optional map[string or number or boolean]` - - `summary: optional "auto" or "concise" or "detailed"` + 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 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`. + - `string` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `number` - - `"auto"` + - `boolean` - - `"concise"` + - `file_id: optional string` - - `"detailed"` + The unique ID of the file. - - `safety_identifier: optional string` + - `filename: 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). + The name of the file. - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + - `score: optional number` - Specifies the processing type used for serving the request. + The relevance score of the file - a value between 0 and 1. - - 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'. + - `text: optional 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 text that was retrieved from the file. - - `"auto"` + - `FunctionCall object { arguments, call_id, name, 6 more }` - - `"default"` + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `"flex"` + - `arguments: string` - - `"scale"` + A JSON string of the arguments to pass to the function. - - `"priority"` + - `call_id: string` - - `status: optional BetaResponseStatus` + The unique ID of the function tool call generated by the model. - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `name: string` - - `"completed"` + The name of the function to run. - - `"failed"` + - `type: "function_call"` - - `"in_progress"` + The type of the function tool call. Always `function_call`. - - `"cancelled"` + - `"function_call"` - - `"queued"` + - `id: optional string` - - `"incomplete"` + The unique ID of the function tool call. - - `text: optional BetaResponseTextConfig` + - `agent: optional object { agent_name }` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + The agent that produced this item. - - [Text inputs and outputs](/docs/guides/text) - - [Structured Outputs](/docs/guides/structured-outputs) + - `agent_name: string` - - `format: optional BetaResponseFormatTextConfig` + The canonical name of the agent that produced this item. - An object specifying the format that the model must output. + - `caller: optional object { type } or object { caller_id, 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). + The execution context that produced this tool call. - The default format is `{ "type": "text" }` with no additional options. + - `Direct object { type }` - **Not recommended for gpt-4o and newer models:** + - `type: "direct"` - 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. + - `"direct"` - - `Text object { type }` + - `Program object { caller_id, type }` - Default response format. Used to generate text responses. + - `caller_id: string` - - `type: "text"` + The call ID of the program item that produced this tool call. - The type of response format being defined. Always `text`. + - `type: "program"` - - `"text"` + - `"program"` - - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` + - `namespace: optional string` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + The namespace of the function to run. - - `name: string` + - `status: optional "in_progress" or "completed" or "incomplete"` - 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 status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `schema: map[unknown]` + - `"in_progress"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `"completed"` - - `type: "json_schema"` + - `"incomplete"` - The type of response format being defined. Always `json_schema`. + - `FunctionCallOutput object { id, call_id, output, 5 more }` - - `"json_schema"` + - `id: string` - - `description: optional string` + The unique ID of the function call tool output. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `call_id: string` - - `strict: optional boolean` + The unique ID of the function tool call generated by 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). + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `JSONObject object { type }` + The output from the function call generated by your code. + Can be a string or an list of output content. - 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. + - `StringOutput = string` - - `type: "json_object"` + A string of the output of the function call. - The type of response format being defined. Always `json_object`. + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `"json_object"` + Text, image, or file output of the function call. - - `verbosity: optional "low" or "medium" or "high"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - 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`. + A text input to the model. - - `"low"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `"medium"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"high"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `top_logprobs: optional number` + A file input to the model. - 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. + - `status: "in_progress" or "completed" or "incomplete"` - - `truncation: optional "auto" or "disabled"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The truncation strategy to use for the model response. + - `"in_progress"` - - `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. + - `"completed"` - - `"auto"` + - `"incomplete"` - - `"disabled"` + - `type: "function_call_output"` - - `usage: optional BetaResponseUsage` + The type of the function tool call output. Always `function_call_output`. - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `"function_call_output"` - - `input_tokens: number` + - `agent: optional object { agent_name }` - The number of input tokens. + The agent that produced this item. - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + - `agent_name: string` - A detailed breakdown of the input tokens. + The canonical name of the agent that produced this item. - - `cache_write_tokens: number` + - `caller: optional object { type } or object { caller_id, type }` - The number of input tokens that were written to the cache. + The execution context that produced this tool call. - - `cached_tokens: number` + - `Direct object { type }` - The number of tokens that were retrieved from the cache. - [More on prompt caching](/docs/guides/prompt-caching). + - `type: "direct"` - - `output_tokens: number` + The caller type. Always `direct`. - The number of output tokens. + - `"direct"` - - `output_tokens_details: object { reasoning_tokens }` + - `Program object { caller_id, type }` - A detailed breakdown of the output tokens. + - `caller_id: string` - - `reasoning_tokens: number` + The call ID of the program item that produced this tool call. - The number of reasoning tokens. + - `type: "program"` - - `total_tokens: number` + The caller type. Always `program`. - The total number of tokens used. + - `"program"` - - `user: optional string` + - `created_by: 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). + The identifier of the actor that created the item. -### Example + - `AgentMessage object { id, author, content, 3 more }` -```http -curl https://api.openai.com/v1/responses/$RESPONSE_ID/cancel \ - -X POST \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `id: string` -#### Response + The unique ID of the agent message. -```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", - "agent": { - "agent_name": "agent_name" - }, - "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" -} -``` + - `author: string` -### Example + The sending agent identity. -```http -curl -X POST https://api.openai.com/v1/responses/resp_123/cancel \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` -#### Response + Encrypted content sent between agents. -```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": {} -} -``` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` -## Compact a response + A text input to the model. -**post** `/responses/compact?beta=true` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` -Compact a conversation. Returns a compacted response object. + A text output from the model. -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). + - `Text object { text, type }` -### Header Parameters + A text content. -- `"openai-beta": optional array of "responses_multi_agent=v1"` + - `text: string` - - `"responses_multi_agent=v1"` + - `type: "text"` -### Body Parameters + - `"text"` -- `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + - `SummaryText object { text, type }` - 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. + A summary text from the model. - - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` + - `text: 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. + A summary of the reasoning output from the model so far. - - `"gpt-5.6-sol"` + - `type: "summary_text"` - - `"gpt-5.6-terra"` + The type of the object. Always `summary_text`. - - `"gpt-5.6-luna"` + - `"summary_text"` - - `"gpt-5.4"` + - `ReasoningText object { text, type }` - - `"gpt-5.4-mini"` + Reasoning text from the model. - - `"gpt-5.4-nano"` + - `text: string` - - `"gpt-5.4-mini-2026-03-17"` + The reasoning text from the model. - - `"gpt-5.4-nano-2026-03-17"` + - `type: "reasoning_text"` - - `"gpt-5.3-chat-latest"` + The type of the reasoning text. Always `reasoning_text`. - - `"gpt-5.2"` + - `"reasoning_text"` - - `"gpt-5.2-2025-12-11"` + - `BetaResponseOutputRefusal object { refusal, type }` - - `"gpt-5.2-chat-latest"` + A refusal from the model. - - `"gpt-5.2-pro"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `"gpt-5.2-pro-2025-12-11"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"gpt-5.1"` + - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` - - `"gpt-5.1-2025-11-13"` + A screenshot of a computer. - - `"gpt-5.1-codex"` + - `detail: "low" or "high" or "auto" or "original"` - - `"gpt-5.1-mini"` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"gpt-5.1-chat-latest"` + - `"low"` - - `"gpt-5"` + - `"high"` - - `"gpt-5-mini"` - - - `"gpt-5-nano"` - - - `"gpt-5-2025-08-07"` - - - `"gpt-5-mini-2025-08-07"` - - - `"gpt-5-nano-2025-08-07"` - - - `"gpt-5-chat-latest"` - - - `"gpt-4.1"` - - - `"gpt-4.1-mini"` + - `"auto"` - - `"gpt-4.1-nano"` + - `"original"` - - `"gpt-4.1-2025-04-14"` + - `file_id: string` - - `"gpt-4.1-mini-2025-04-14"` + The identifier of an uploaded file that contains the screenshot. - - `"gpt-4.1-nano-2025-04-14"` + - `image_url: string` - - `"o4-mini"` + The URL of the screenshot image. - - `"o4-mini-2025-04-16"` + - `type: "computer_screenshot"` - - `"o3"` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `"o3-2025-04-16"` + - `"computer_screenshot"` - - `"o3-mini"` + - `prompt_cache_breakpoint: optional object { mode }` - - `"o3-mini-2025-01-31"` + 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. - - `"o1"` + - `mode: "explicit"` - - `"o1-2024-12-17"` + The breakpoint mode. Always `explicit`. - - `"o1-preview"` + - `"explicit"` - - `"o1-preview-2024-09-12"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `"o1-mini"` + A file input to the model. - - `"o1-mini-2024-09-12"` + - `EncryptedContent object { encrypted_content, type }` - - `"gpt-4o"` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `"gpt-4o-2024-11-20"` + - `encrypted_content: string` - - `"gpt-4o-2024-08-06"` + Opaque encrypted content. - - `"gpt-4o-2024-05-13"` + - `type: "encrypted_content"` - - `"gpt-4o-audio-preview"` + The type of the input item. Always `encrypted_content`. - - `"gpt-4o-audio-preview-2024-10-01"` + - `"encrypted_content"` - - `"gpt-4o-audio-preview-2024-12-17"` + - `recipient: string` - - `"gpt-4o-audio-preview-2025-06-03"` + The destination agent identity. - - `"gpt-4o-mini-audio-preview"` + - `type: "agent_message"` - - `"gpt-4o-mini-audio-preview-2024-12-17"` + The type of the item. Always `agent_message`. - - `"gpt-4o-search-preview"` + - `"agent_message"` - - `"gpt-4o-mini-search-preview"` + - `agent: optional object { agent_name }` - - `"gpt-4o-search-preview-2025-03-11"` + The agent that produced this item. - - `"gpt-4o-mini-search-preview-2025-03-11"` + - `agent_name: string` - - `"chatgpt-4o-latest"` + The canonical name of the agent that produced this item. - - `"codex-mini-latest"` + - `MultiAgentCall object { id, action, arguments, 3 more }` - - `"gpt-4o-mini"` + - `id: string` - - `"gpt-4o-mini-2024-07-18"` + The unique ID of the multi-agent call item. - - `"gpt-4-turbo"` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `"gpt-4-turbo-2024-04-09"` + The multi-agent action to execute. - - `"gpt-4-0125-preview"` + - `"spawn_agent"` - - `"gpt-4-turbo-preview"` + - `"interrupt_agent"` - - `"gpt-4-1106-preview"` + - `"list_agents"` - - `"gpt-4-vision-preview"` + - `"send_message"` - - `"gpt-4"` + - `"followup_task"` - - `"gpt-4-0314"` + - `"wait_agent"` - - `"gpt-4-0613"` + - `arguments: string` - - `"gpt-4-32k"` + The JSON string of arguments generated for the action. - - `"gpt-4-32k-0314"` + - `call_id: string` - - `"gpt-4-32k-0613"` + The unique ID linking this call to its output. - - `"gpt-3.5-turbo"` + - `type: "multi_agent_call"` - - `"gpt-3.5-turbo-16k"` + The type of the multi-agent call. Always `multi_agent_call`. - - `"gpt-3.5-turbo-0301"` + - `"multi_agent_call"` - - `"gpt-3.5-turbo-0613"` + - `agent: optional object { agent_name }` - - `"gpt-3.5-turbo-1106"` + The agent that produced this item. - - `"gpt-3.5-turbo-0125"` + - `agent_name: string` - - `"gpt-3.5-turbo-16k-0613"` + The canonical name of the agent that produced this item. - - `"o1-pro"` + - `MultiAgentCallOutput object { id, action, call_id, 3 more }` - - `"o1-pro-2025-03-19"` + - `id: string` - - `"o3-pro"` + The unique ID of the multi-agent call output item. - - `"o3-pro-2025-06-10"` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `"o3-deep-research"` + The multi-agent action that produced this result. - - `"o3-deep-research-2025-06-26"` + - `"spawn_agent"` - - `"o4-mini-deep-research"` + - `"interrupt_agent"` - - `"o4-mini-deep-research-2025-06-26"` + - `"list_agents"` - - `"computer-use-preview"` + - `"send_message"` - - `"computer-use-preview-2025-03-11"` + - `"followup_task"` - - `"gpt-5-codex"` + - `"wait_agent"` - - `"gpt-5-pro"` + - `call_id: string` - - `"gpt-5-pro-2025-10-06"` + The unique ID of the multi-agent call. - - `"gpt-5.1-codex-max"` + - `output: array of BetaResponseOutputText` - - `string` + Text output returned by the multi-agent action. -- `input: optional string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - Text, image, or file inputs to the model, used to generate a response + The annotations of the text output. - - `string` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - A text input to the model, equivalent to a text input with the `user` role. + - `text: string` - - `array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + The text output from the model. - A list of one or many input items to the model, containing different content types. + - `type: "output_text"` - - `BetaEasyInputMessage object { content, role, phase, type }` + The type of the output text. Always `output_text`. - 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: "multi_agent_call_output"` - - `content: string or BetaResponseInputMessageContentList` + The type of the multi-agent result. Always `multi_agent_call_output`. - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `"multi_agent_call_output"` - - `TextInput = string` + - `agent: optional object { agent_name }` - A text input to the model. + The agent that produced this item. - - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` + - `agent_name: string` - A list of one or many input items to the model, containing different content - types. + The canonical name of the agent that produced this item. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `WebSearchCall object { id, action, status, 2 more }` - A text input to the model. + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `text: string` + - `id: string` - The text input to the model. + The unique ID of the web search tool call. - - `type: "input_text"` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - The type of the input item. Always `input_text`. + 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). - - `"input_text"` + - `Search object { type, queries, query, sources }` - - `prompt_cache_breakpoint: optional object { mode }` + Action type "search" - Performs a web search query. - 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: "search"` - - `mode: "explicit"` + The action type. - The breakpoint mode. Always `explicit`. + - `"search"` - - `"explicit"` + - `queries: optional array of string` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + The search queries. - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `query: optional string` - - `detail: "low" or "high" or "auto" or "original"` + The search query. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `sources: optional array of object { type, url }` - - `"low"` + The sources used in the search. - - `"high"` + - `type: "url"` - - `"auto"` + The type of source. Always `url`. - - `"original"` + - `"url"` - - `type: "input_image"` + - `url: string` - The type of the input item. Always `input_image`. + The URL of the source. - - `"input_image"` + - `OpenPage object { type, url }` - - `file_id: optional string` + Action type "open_page" - Opens a specific URL from search results. - The ID of the file to be sent to the model. + - `type: "open_page"` - - `image_url: optional string` + The action type. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `"open_page"` - - `prompt_cache_breakpoint: optional object { mode }` + - `url: 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 URL opened by the model. - - `mode: "explicit"` + - `FindInPage object { pattern, type, url }` - The breakpoint mode. Always `explicit`. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `"explicit"` + - `pattern: string` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + The pattern or text to search for within the page. - A file input to the model. + - `type: "find_in_page"` - - `type: "input_file"` + The action type. - The type of the input item. Always `input_file`. + - `"find_in_page"` - - `"input_file"` + - `url: string` - - `detail: optional "auto" or "low" or "high"` + The URL of the page searched for the pattern. - 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`. + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `"auto"` + The status of the web search tool call. - - `"low"` + - `"in_progress"` - - `"high"` + - `"searching"` - - `file_data: optional string` + - `"completed"` - The content of the file to be sent to the model. + - `"failed"` - - `file_id: optional string` + - `type: "web_search_call"` - The ID of the file to be sent to the model. + The type of the web search tool call. Always `web_search_call`. - - `file_url: optional string` + - `"web_search_call"` - The URL of the file to be sent to the model. + - `agent: optional object { agent_name }` - - `filename: optional string` + The agent that produced this item. - The name of the file to be sent to the model. + - `agent_name: string` - - `prompt_cache_breakpoint: optional object { mode }` + The canonical name of the agent that produced this item. - 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. + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - - `mode: "explicit"` + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - The breakpoint mode. Always `explicit`. + - `id: string` - - `"explicit"` + The unique ID of the computer call. - - `role: "user" or "assistant" or "system" or "developer"` + - `call_id: string` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + An identifier used when responding to the tool call with output. - - `"user"` + - `pending_safety_checks: array of object { id, code, message }` - - `"assistant"` + The pending safety checks for the computer call. - - `"system"` + - `id: string` - - `"developer"` + The ID of the pending safety check. - - `phase: optional "commentary" or "final_answer"` + - `code: optional string` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + The type of the pending safety check. - - `"commentary"` + - `message: optional string` - - `"final_answer"` + Details about the pending safety check. - - `type: optional "message"` + - `status: "in_progress" or "completed" or "incomplete"` - The type of the message input. Always `message`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"message"` + - `"in_progress"` - - `Message object { content, role, agent, 2 more }` + - `"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. + - `"incomplete"` - - `content: BetaResponseInputMessageContentList` + - `type: "computer_call"` - A list of one or many input items to the model, containing different content - types. + The type of the computer call. Always `computer_call`. - - `role: "user" or "system" or "developer"` + - `"computer_call"` - The role of the message input. One of `user`, `system`, or `developer`. + - `action: optional BetaComputerAction` - - `"user"` + A click action. - - `"system"` + - `actions: optional BetaComputerActionList` - - `"developer"` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - `agent: optional object { agent_name }` @@ -40920,201 +41708,197 @@ Learn when and how to compact long-running conversations in the [conversation st The canonical name of the agent that produced this item. - - `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"` + - `ComputerCallOutput object { id, call_id, output, 5 more }` - The type of the message input. Always set to `message`. + - `id: string` - - `"message"` + The unique ID of the computer call tool output. - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + - `call_id: string` - An output message from the model. + The ID of the computer tool call that produced the output. - - `id: string` + - `output: BetaResponseComputerToolCallOutputScreenshot` - The unique ID of the output message. + A computer screenshot image used with the computer use tool. - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - The content of the output message. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `BetaResponseOutputText object { annotations, logprobs, text, type }` + - `"completed"` - A text output from the model. + - `"incomplete"` - - `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 }` + - `"failed"` - The annotations of the text output. + - `"in_progress"` - - `FileCitation object { file_id, filename, index, type }` + - `type: "computer_call_output"` - A citation to a file. + The type of the computer tool call output. Always `computer_call_output`. - - `file_id: string` + - `"computer_call_output"` - The ID of the file. + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `filename: string` + The safety checks reported by the API that have been acknowledged by the + developer. - The filename of the file cited. + - `id: string` - - `index: number` + The ID of the pending safety check. - The index of the file in the list of files. + - `code: optional string` - - `type: "file_citation"` + The type of the pending safety check. - The type of the file citation. Always `file_citation`. + - `message: optional string` - - `"file_citation"` + Details about the pending safety check. - - `URLCitation object { end_index, start_index, title, 2 more }` + - `agent: optional object { agent_name }` - A citation for a web resource used to generate a model response. + The agent that produced this item. - - `end_index: number` + - `agent_name: string` - The index of the last character of the URL citation in the message. + The canonical name of the agent that produced this item. - - `start_index: number` + - `created_by: optional string` - The index of the first character of the URL citation in the message. + The identifier of the actor that created the item. - - `title: string` + - `Reasoning object { id, summary, type, 4 more }` - The title of the web resource. + 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: "url_citation"` + - `id: string` - The type of the URL citation. Always `url_citation`. + The unique identifier of the reasoning content. - - `"url_citation"` + - `summary: array of object { text, type }` - - `url: string` + Reasoning summary content. - The URL of the web resource. + - `text: string` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + A summary of the reasoning output from the model so far. - A citation for a container file used to generate a model response. + - `type: "summary_text"` - - `container_id: string` + The type of the object. Always `summary_text`. - The ID of the container file. + - `"summary_text"` - - `end_index: number` + - `type: "reasoning"` - The index of the last character of the container file citation in the message. + The type of the object. Always `reasoning`. - - `file_id: string` + - `"reasoning"` - The ID of the file. + - `agent: optional object { agent_name }` - - `filename: string` + The agent that produced this item. - The filename of the container file cited. + - `agent_name: string` - - `start_index: number` + The canonical name of the agent that produced this item. - The index of the first character of the container file citation in the message. + - `content: optional array of object { text, type }` - - `type: "container_file_citation"` + Reasoning text content. - The type of the container file citation. Always `container_file_citation`. + - `text: string` - - `"container_file_citation"` + The reasoning text from the model. - - `FilePath object { file_id, index, type }` + - `type: "reasoning_text"` - A path to a file. + The type of the reasoning text. Always `reasoning_text`. - - `file_id: string` + - `"reasoning_text"` - The ID of the file. + - `encrypted_content: optional string` - - `index: number` + 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 index of the file in the list of files. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `type: "file_path"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The type of the file path. Always `file_path`. + - `"in_progress"` - - `"file_path"` + - `"completed"` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `"incomplete"` - - `token: string` + - `Program object { id, call_id, code, 3 more }` - - `bytes: array of number` + - `id: string` - - `logprob: number` + The unique ID of the program item. - - `top_logprobs: array of object { token, bytes, logprob }` + - `call_id: string` - - `token: string` + The stable call ID of the program item. - - `bytes: array of number` + - `code: string` - - `logprob: number` + The JavaScript source executed by programmatic tool calling. - - `text: string` + - `fingerprint: string` - The text output from the model. + Opaque program replay fingerprint that must be round-tripped. - - `type: "output_text"` + - `type: "program"` - The type of the output text. Always `output_text`. + The type of the item. Always `program`. - - `"output_text"` + - `"program"` - - `BetaResponseOutputRefusal object { refusal, type }` + - `agent: optional object { agent_name }` - A refusal from the model. + The agent that produced this item. - - `refusal: string` + - `agent_name: string` - The refusal explanation from the model. + The canonical name of the agent that produced this item. - - `type: "refusal"` + - `ProgramOutput object { id, call_id, result, 3 more }` - The type of the refusal. Always `refusal`. + - `id: string` - - `"refusal"` + The unique ID of the program output item. - - `role: "assistant"` + - `call_id: string` - The role of the output message. Always `assistant`. + The call ID of the program item. - - `"assistant"` + - `result: string` - - `status: "in_progress" or "completed" or "incomplete"` + The result produced by the program item. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `status: "completed" or "incomplete"` - - `"in_progress"` + The terminal status of the program output item. - `"completed"` - `"incomplete"` - - `type: "message"` + - `type: "program_output"` - The type of the output message. Always `message`. + The type of the item. Always `program_output`. - - `"message"` + - `"program_output"` - `agent: optional object { agent_name }` @@ -41124,49 +41908,43 @@ Learn when and how to compact long-running conversations in the [conversation st The canonical name of the agent that produced this item. - - `phase: optional "commentary" or "final_answer"` + - `ToolSearchCall object { id, arguments, call_id, 5 more }` - 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. + - `id: string` - - `"commentary"` + The unique ID of the tool search call item. - - `"final_answer"` + - `arguments: unknown` - - `FileSearchCall object { id, queries, status, 3 more }` + Arguments used for the tool search call. - The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + - `call_id: string` - - `id: string` + The unique ID of the tool search call generated by the model. - The unique ID of the file search tool call. + - `execution: "server" or "client"` - - `queries: array of string` + Whether tool search was executed by the server or by the client. - The queries used to search for files. + - `"server"` - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `"client"` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `status: "in_progress" or "completed" or "incomplete"` - - `"in_progress"` + The status of the tool search call item that was recorded. - - `"searching"` + - `"in_progress"` - `"completed"` - `"incomplete"` - - `"failed"` - - - `type: "file_search_call"` + - `type: "tool_search_call"` - The type of the file search tool call. Always `file_search_call`. + The type of the item. Always `tool_search_call`. - - `"file_search_call"` + - `"tool_search_call"` - `agent: optional object { agent_name }` @@ -41176,1002 +41954,1036 @@ Learn when and how to compact long-running conversations in the [conversation st The canonical name of the agent that produced this item. - - `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]` + - `created_by: optional string` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + The identifier of the actor that created the item. - - `string` + - `ToolSearchOutput object { id, call_id, execution, 5 more }` - - `number` + - `id: string` - - `boolean` + The unique ID of the tool search output item. - - `file_id: optional string` + - `call_id: string` - The unique ID of the file. + The unique ID of the tool search call generated by the model. - - `filename: optional string` + - `execution: "server" or "client"` - The name of the file. + Whether tool search was executed by the server or by the client. - - `score: optional number` + - `"server"` - The relevance score of the file - a value between 0 and 1. + - `"client"` - - `text: optional string` + - `status: "in_progress" or "completed" or "incomplete"` - The text that was retrieved from the file. + The status of the tool search output item that was recorded. - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + - `"in_progress"` - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + - `"completed"` - - `id: string` + - `"incomplete"` - The unique ID of the computer call. + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - - `call_id: string` + The loaded tool definitions returned by tool search. - An identifier used when responding to the tool call with output. + - `Function object { name, parameters, strict, 5 more }` - - `pending_safety_checks: array of object { id, code, 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). - The pending safety checks for the computer call. + - `name: string` - - `id: string` + The name of the function to call. - The ID of the pending safety check. + - `parameters: map[unknown]` - - `code: optional string` + A JSON schema object describing the parameters of the function. - The type of the pending safety check. + - `strict: boolean` - - `message: optional string` + Whether strict parameter validation is enforced for this function tool. - Details about the pending safety check. + - `type: "function"` - - `status: "in_progress" or "completed" or "incomplete"` + The type of the function tool. Always `function`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"function"` - - `"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`. + - `defer_loading: optional boolean` - - `"computer_call"` + Whether this function is deferred and loaded via tool search. - - `action: optional BetaComputerAction` + - `description: optional string` - A click action. + A description of the function. Used by the model to determine whether or not to call the function. - - `Click object { button, type, x, 2 more }` + - `output_schema: optional map[unknown]` - A click action. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `button: "left" or "right" or "wheel" or 2 more` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + 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). - - `"left"` + - `type: "file_search"` - - `"right"` + The type of the file search tool. Always `file_search`. - - `"wheel"` + - `"file_search"` - - `"back"` + - `vector_store_ids: array of string` - - `"forward"` + The IDs of the vector stores to search. - - `type: "click"` + - `filters: optional object { key, type, value } or object { filters, type }` - Specifies the event type. For a click action, this property is always `click`. + A filter to apply. - - `"click"` + - `ComparisonFilter object { key, type, value }` - - `x: number` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The x-coordinate where the click occurred. + - `key: string` - - `y: number` + The key to compare against the value. - The y-coordinate where the click occurred. + - `type: "eq" or "ne" or "gt" or 5 more` - - `keys: optional array of string` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The keys being held while clicking. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `DoubleClick object { keys, type, x, y }` + - `"eq"` - A double click action. + - `"ne"` - - `keys: array of string` + - `"gt"` - The keys being held while double-clicking. + - `"gte"` - - `type: "double_click"` + - `"lt"` - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `"lte"` - - `"double_click"` + - `"in"` - - `x: number` + - `"nin"` - The x-coordinate where the double click occurred. + - `value: string or number or boolean or array of string or number` - - `y: number` + The value to compare against the attribute key; supports string, number, or boolean types. - The y-coordinate where the double click occurred. + - `string` - - `Drag object { path, type, keys }` + - `number` - A drag action. + - `boolean` - - `path: array of object { x, y }` + - `array of string or number` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `string` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `number` - - `x: number` + - `CompoundFilter object { filters, type }` - The x-coordinate. + Combine multiple filters using `and` or `or`. - - `y: number` + - `filters: array of object { key, type, value } or unknown` - The y-coordinate. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `type: "drag"` + - `ComparisonFilter object { key, type, value }` - Specifies the event type. For a drag action, this property is always set to `drag`. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"drag"` + - `key: string` - - `keys: optional array of string` + The key to compare against the value. - The keys being held while dragging the mouse. + - `type: "eq" or "ne" or "gt" or 5 more` - - `Keypress object { keys, type }` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - A collection of keypresses the model would like to perform. + - `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 - - `keys: array of string` + - `"eq"` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `"ne"` - - `type: "keypress"` + - `"gt"` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `"gte"` - - `"keypress"` + - `"lt"` - - `Move object { type, x, y, keys }` + - `"lte"` - A mouse move action. + - `"in"` - - `type: "move"` + - `"nin"` - Specifies the event type. For a move action, this property is always set to `move`. + - `value: string or number or boolean or array of string or number` - - `"move"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `x: number` + - `string` - The x-coordinate to move to. + - `number` - - `y: number` + - `boolean` - The y-coordinate to move to. + - `array of string or number` - - `keys: optional array of string` + - `string` - The keys being held while moving the mouse. + - `number` - - `Screenshot object { type }` + - `unknown` - A screenshot action. + - `type: "and" or "or"` - - `type: "screenshot"` + Type of operation: `and` or `or`. - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `"and"` - - `"screenshot"` + - `"or"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `max_num_results: optional number` - A scroll action. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `scroll_x: number` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - The horizontal scroll distance. + Ranking options for search. - - `scroll_y: number` + - `hybrid_search: optional object { embedding_weight, text_weight }` - The vertical scroll distance. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `type: "scroll"` + - `embedding_weight: number` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + The weight of the embedding in the reciprocal ranking fusion. - - `"scroll"` + - `text_weight: number` - - `x: number` + The weight of the text in the reciprocal ranking fusion. - The x-coordinate where the scroll occurred. + - `ranker: optional "auto" or "default-2024-11-15"` - - `y: number` + The ranker to use for the file search. - The y-coordinate where the scroll occurred. + - `"auto"` - - `keys: optional array of string` + - `"default-2024-11-15"` - The keys being held while scrolling. + - `score_threshold: optional number` - - `Type object { text, type }` + 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. - An action to type in text. + - `Computer object { type }` - - `text: string` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The text to type. + - `type: "computer"` - - `type: "type"` + The type of the computer tool. Always `computer`. - Specifies the event type. For a type action, this property is always set to `type`. + - `"computer"` - - `"type"` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `Wait object { type }` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - A wait action. + - `display_height: number` - - `type: "wait"` + The height of the computer display. - Specifies the event type. For a wait action, this property is always set to `wait`. + - `display_width: number` - - `"wait"` + The width of the computer display. - - `actions: optional BetaComputerActionList` + - `environment: "windows" or "mac" or "linux" or 2 more` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + The type of computer environment to control. - - `Click object { button, type, x, 2 more }` + - `"windows"` - A click action. + - `"mac"` - - `DoubleClick object { keys, type, x, y }` + - `"linux"` - A double click action. + - `"ubuntu"` - - `Drag object { path, type, keys }` + - `"browser"` - A drag action. + - `type: "computer_use_preview"` - - `Keypress object { keys, type }` + The type of the computer use tool. Always `computer_use_preview`. - A collection of keypresses the model would like to perform. + - `"computer_use_preview"` - - `Move object { type, x, y, keys }` + - `WebSearch object { type, filters, search_context_size, user_location }` - A mouse move action. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `Screenshot object { type }` + - `type: "web_search" or "web_search_2025_08_26"` - A screenshot action. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `"web_search"` - A scroll action. + - `"web_search_2025_08_26"` - - `Type object { text, type }` + - `filters: optional object { allowed_domains }` - An action to type in text. + Filters for the search. - - `Wait object { type }` + - `allowed_domains: optional array of string` - A wait action. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `agent: optional object { agent_name }` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - The agent that produced this item. + - `search_context_size: optional "low" or "medium" or "high"` - - `agent_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 canonical name of the agent that produced this item. + - `"low"` - - `ComputerCallOutput object { call_id, output, type, 4 more }` + - `"medium"` - The output of a computer tool call. + - `"high"` - - `call_id: string` + - `user_location: optional object { city, country, region, 2 more }` - The ID of the computer tool call that produced the output. + The approximate location of the user. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `city: optional string` - A computer screenshot image used with the computer use tool. + Free text input for the city of the user, e.g. `San Francisco`. - - `type: "computer_screenshot"` + - `country: optional string` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"computer_screenshot"` + - `region: optional string` - - `file_id: optional string` + Free text input for the region of the user, e.g. `California`. - The identifier of an uploaded file that contains the screenshot. + - `timezone: optional string` - - `image_url: optional string` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The URL of the screenshot image. + - `type: optional "approximate"` - - `type: "computer_call_output"` + The type of location approximation. Always `approximate`. - The type of the computer tool call output. Always `computer_call_output`. + - `"approximate"` - - `"computer_call_output"` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `id: optional string` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - The ID of the computer tool call output. + - `server_label: string` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + A label for this MCP server, used to identify it in tool calls. - The safety checks reported by the API that have been acknowledged by the developer. + - `type: "mcp"` - - `id: string` + The type of the MCP tool. Always `mcp`. - The ID of the pending safety check. + - `"mcp"` - - `code: optional string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The type of the pending safety check. + The tool invocation context(s). - - `message: optional string` + - `"direct"` - Details about the pending safety check. + - `"programmatic"` - - `agent: optional object { agent_name }` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - The agent that produced this item. + List of allowed tool names or a filter object. - - `agent_name: string` + - `McpAllowedTools = array of string` - The canonical name of the agent that produced this item. + A string array of allowed tool names - - `status: optional "in_progress" or "completed" or "incomplete"` + - `McpToolFilter object { read_only, tool_names }` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + A filter object to specify which tools are allowed. - - `"in_progress"` + - `read_only: optional boolean` - - `"completed"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `"incomplete"` + - `tool_names: optional array of string` - - `WebSearchCall object { id, action, status, 2 more }` + List of allowed tool names. - The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + - `authorization: optional string` - - `id: string` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - The unique ID of the web search tool call. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + 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). - 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). + Currently supported `connector_id` values are: - - `Search object { type, queries, query, sources }` + - 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` - Action type "search" - Performs a web search query. + - `"connector_dropbox"` - - `type: "search"` + - `"connector_gmail"` - The action type. + - `"connector_googlecalendar"` - - `"search"` + - `"connector_googledrive"` - - `queries: optional array of string` + - `"connector_microsoftteams"` - The search queries. + - `"connector_outlookcalendar"` - - `query: optional string` + - `"connector_outlookemail"` - The search query. + - `"connector_sharepoint"` - - `sources: optional array of object { type, url }` + - `defer_loading: optional boolean` - The sources used in the search. + Whether this MCP tool is deferred and discovered via tool search. - - `type: "url"` + - `headers: optional map[string]` - The type of source. Always `url`. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `"url"` + - `require_approval: optional object { always, never } or "always" or "never"` - - `url: string` + Specify which of the MCP server's tools require approval. - The URL of the source. + - `McpToolApprovalFilter object { always, never }` - - `OpenPage object { type, url }` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - Action type "open_page" - Opens a specific URL from search results. + - `always: optional object { read_only, tool_names }` - - `type: "open_page"` + A filter object to specify which tools are allowed. - The action type. + - `read_only: optional boolean` - - `"open_page"` + 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. - - `url: optional string` + - `tool_names: optional array of string` - The URL opened by the model. + List of allowed tool names. - - `FindInPage object { pattern, type, url }` + - `never: optional object { read_only, tool_names }` - Action type "find_in_page": Searches for a pattern within a loaded page. + A filter object to specify which tools are allowed. - - `pattern: string` + - `read_only: optional boolean` - The pattern or text to search for within the page. + 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: "find_in_page"` + - `tool_names: optional array of string` - The action type. + List of allowed tool names. - - `"find_in_page"` + - `McpToolApprovalSetting = "always" or "never"` - - `url: 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. - The URL of the page searched for the pattern. + - `"always"` - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `"never"` - The status of the web search tool call. + - `server_description: optional string` - - `"in_progress"` + Optional description of the MCP server, used to provide more context. - - `"searching"` + - `server_url: optional string` - - `"completed"` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `"failed"` + - `tunnel_id: optional string` - - `type: "web_search_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. - The type of the web search tool call. Always `web_search_call`. + - `CodeInterpreter object { container, type, allowed_callers }` - - `"web_search_call"` + A tool that runs Python code to help generate a response to a prompt. - - `agent: optional object { agent_name }` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - The agent that produced this item. + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - - `agent_name: string` + - `string` - The canonical name of the agent that produced this item. + The container ID. - - `FunctionCall object { arguments, call_id, name, 6 more }` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - A tool call to run a function. See the - [function calling guide](/docs/guides/function-calling) for more information. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `arguments: string` + - `type: "auto"` - A JSON string of the arguments to pass to the function. + Always `auto`. - - `call_id: string` + - `"auto"` - The unique ID of the function tool call generated by the model. + - `file_ids: optional array of string` - - `name: string` + An optional list of uploaded files to make available to your code. - The name of the function to run. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `type: "function_call"` + The memory limit for the code interpreter container. - The type of the function tool call. Always `function_call`. + - `"1g"` - - `"function_call"` + - `"4g"` - - `id: optional string` + - `"16g"` - The unique ID of the function tool call. + - `"64g"` - - `agent: optional object { agent_name }` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - The agent that produced this item. + Network access policy for the container. - - `agent_name: string` + - `BetaContainerNetworkPolicyDisabled object { type }` - The canonical name of the agent that produced this item. + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `caller: optional object { type } or object { caller_id, type }` + - `type: "code_interpreter"` - The execution context that produced this tool call. + The type of the code interpreter tool. Always `code_interpreter`. - - `Direct object { type }` + - `"code_interpreter"` - - `type: "direct"` + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). - `"direct"` - - `Program object { caller_id, type }` + - `"programmatic"` - - `caller_id: string` + - `ProgrammaticToolCalling object { type }` - The call ID of the program item that produced this tool call. + - `type: "programmatic_tool_calling"` - - `type: "program"` + The type of the tool. Always `programmatic_tool_calling`. - - `"program"` + - `"programmatic_tool_calling"` - - `namespace: optional string` + - `ImageGeneration object { type, action, background, 9 more }` - The namespace of the function to run. + A tool that generates images using the GPT image models. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `type: "image_generation"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The type of the image generation tool. Always `image_generation`. - - `"in_progress"` + - `"image_generation"` - - `"completed"` + - `action: optional "generate" or "edit" or "auto"` - - `"incomplete"` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `FunctionCallOutput object { call_id, output, type, 4 more }` + - `"generate"` - The output of a function tool call. + - `"edit"` - - `call_id: string` + - `"auto"` - The unique ID of the function tool call generated by the model. + - `background: optional "transparent" or "opaque" or "auto"` - - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - Text, image, or file output of the function tool call. + - `"transparent"` - - `string` + - `"opaque"` - A JSON string of the output of the function tool call. + - `"auto"` - - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` + - `input_fidelity: optional "high" or "low"` - An array of content outputs (text, image, file) for the function tool call. + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + - `"high"` - A text input to the model. + - `"low"` - - `text: string` + - `input_image_mask: optional object { file_id, image_url }` - The text input to the model. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `type: "input_text"` + - `file_id: optional string` - The type of the input item. Always `input_text`. + File ID for the mask image. - - `"input_text"` + - `image_url: optional string` - - `prompt_cache_breakpoint: optional object { mode }` + Base64-encoded mask 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. + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `mode: "explicit"` + The image generation model to use. Default: `gpt-image-1`. - The breakpoint mode. Always `explicit`. + - `string` - - `"explicit"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + The image generation model to use. Default: `gpt-image-1`. - An image input to the model. Learn about [image inputs](/docs/guides/vision) + - `"gpt-image-1"` - - `type: "input_image"` + - `"gpt-image-1-mini"` - The type of the input item. Always `input_image`. + - `"gpt-image-1.5"` - - `"input_image"` + - `moderation: optional "auto" or "low"` - - `detail: optional "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"` - - `file_id: optional string` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The ID of the file to be sent to the model. + - `"png"` - - `image_url: optional string` + - `"webp"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `"jpeg"` - - `prompt_cache_breakpoint: optional object { mode }` + - `partial_images: optional number` - 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. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `mode: "explicit"` + - `quality: optional "low" or "medium" or "high" or "auto"` - The breakpoint mode. Always `explicit`. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `"explicit"` + - `"low"` - - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` + - `"medium"` - A file input to the model. + - `"high"` - - `type: "input_file"` + - `"auto"` - The type of the input item. Always `input_file`. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `"input_file"` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `detail: optional "auto" or "low" or "high"` + - `string` - 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`. + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `"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`. - - `"low"` + - `"1024x1024"` - - `"high"` + - `"1024x1536"` - - `file_data: optional string` + - `"1536x1024"` - The base64-encoded data of the file to be sent to the model. + - `"auto"` - - `file_id: optional string` + - `LocalShell object { type }` - The ID of the file to be sent to the model. + A tool that allows the model to execute shell commands in a local environment. - - `file_url: optional string` + - `type: "local_shell"` - The URL of the file to be sent to the model. + The type of the local shell tool. Always `local_shell`. - - `filename: optional string` + - `"local_shell"` - The name of the file to be sent to the model. + - `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"` - - `type: "function_call_output"` + The tool invocation context(s). - The type of the function tool call output. Always `function_call_output`. + - `"direct"` - - `"function_call_output"` + - `"programmatic"` - - `id: optional string` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - The unique ID of the function tool call output. Populated when this item is returned via API. + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `agent: optional object { agent_name }` + - `BetaLocalEnvironment object { type, skills }` - The agent that produced this item. + - `BetaContainerReference object { container_id, type }` - - `agent_name: string` + - `Custom object { name, type, allowed_callers, 3 more }` - The canonical name of the agent that produced this item. + 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`. - The caller type. Always `direct`. + - `"custom"` + + - `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 tool should be deferred and discovered via tool search. - - `type: "program"` + - `description: optional string` - The caller type. Always `program`. + Optional description of the custom tool, used to provide more context. - - `"program"` + - `format: optional object { type } or object { definition, syntax, type }` - - `status: optional "in_progress" or "completed" or "incomplete"` + The input format for the custom tool. Default is unconstrained text. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `Text object { type }` - - `"in_progress"` + Unconstrained free-form text. - - `"completed"` + - `type: "text"` - - `"incomplete"` + Unconstrained text format. Always `text`. - - `AgentMessage object { author, content, recipient, 3 more }` + - `"text"` - A message routed between agents. + - `Grammar object { definition, syntax, type }` - - `author: string` + A grammar defined by the user. - The sending agent identity. + - `definition: string` - - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` + The grammar definition. - Plaintext, image, or encrypted content sent between agents. + - `syntax: "lark" or "regex"` - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + The syntax of the grammar definition. One of `lark` or `regex`. - A text input to the model. + - `"lark"` - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + - `"regex"` - An image input to the model. Learn about [image inputs](/docs/guides/vision) + - `type: "grammar"` - - `EncryptedContent object { encrypted_content, type }` + Grammar format. Always `grammar`. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `"grammar"` - - `encrypted_content: string` + - `Namespace object { description, name, tools, type }` - Opaque encrypted content. + Groups function/custom tools under a shared namespace. - - `type: "encrypted_content"` + - `description: string` - The type of the input item. Always `encrypted_content`. + A description of the namespace shown to the model. - - `"encrypted_content"` + - `name: string` - - `recipient: string` + The namespace name used in tool calls (for example, `crm`). - The destination agent identity. + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `type: "agent_message"` + The function/custom tools available inside this namespace. - The item type. Always `agent_message`. + - `Function object { name, type, allowed_callers, 5 more }` - - `"agent_message"` + - `name: string` - - `id: optional string` + - `type: "function"` - The unique ID of this agent message item. + - `"function"` - - `agent: optional object { agent_name }` + - `allowed_callers: optional array of "direct" or "programmatic"` - The agent that produced this item. + The tool invocation context(s). - - `agent_name: string` + - `"direct"` - The canonical name of the agent that produced this item. + - `"programmatic"` - - `MultiAgentCall object { action, arguments, call_id, 3 more }` + - `defer_loading: optional boolean` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + Whether this function should be deferred and discovered via tool search. - The multi-agent action that was executed. + - `description: optional string` - - `"spawn_agent"` + - `output_schema: optional map[unknown]` - - `"interrupt_agent"` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `"list_agents"` + - `parameters: optional unknown` - - `"send_message"` + - `strict: optional boolean` - - `"followup_task"` + 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. - - `"wait_agent"` + - `Custom object { name, type, allowed_callers, 3 more }` - - `arguments: string` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - The action arguments as a JSON string. + - `name: string` - - `call_id: string` + The name of the custom tool, used to identify it in tool calls. - The unique ID linking this call to its output. + - `type: "custom"` - - `type: "multi_agent_call"` + The type of the custom tool. Always `custom`. - The item type. Always `multi_agent_call`. + - `"custom"` - - `"multi_agent_call"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `id: optional string` + The tool invocation context(s). - The unique ID of this multi-agent call. + - `"direct"` - - `agent: optional object { agent_name }` + - `"programmatic"` - The agent that produced this item. + - `defer_loading: optional boolean` - - `agent_name: string` + Whether this tool should be deferred and discovered via tool search. - The canonical name of the agent that produced this item. + - `description: optional string` - - `MultiAgentCallOutput object { action, call_id, output, 3 more }` + Optional description of the custom tool, used to provide more context. - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `format: optional object { type } or object { definition, syntax, type }` - The multi-agent action that produced this result. + The input format for the custom tool. Default is unconstrained text. - - `"spawn_agent"` + - `Text object { type }` - - `"interrupt_agent"` + Unconstrained free-form text. - - `"list_agents"` + - `type: "text"` - - `"send_message"` + Unconstrained text format. Always `text`. - - `"followup_task"` + - `"text"` - - `"wait_agent"` + - `Grammar object { definition, syntax, type }` - - `call_id: string` + A grammar defined by the user. - The unique ID of the multi-agent call. + - `definition: string` - - `output: array of object { text, type, annotations }` + The grammar definition. - Text output returned by the multi-agent action. + - `syntax: "lark" or "regex"` - - `text: string` + The syntax of the grammar definition. One of `lark` or `regex`. - The text content. + - `"lark"` - - `type: "output_text"` + - `"regex"` - The content type. Always `output_text`. + - `type: "grammar"` - - `"output_text"` + Grammar format. Always `grammar`. - - `annotations: optional 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 }` + - `"grammar"` - Citations associated with the text content. + - `type: "namespace"` - - `FileCitation object { file_id, filename, index, type }` + The type of the tool. Always `namespace`. - - `file_id: string` + - `"namespace"` - The ID of the file. + - `ToolSearch object { type, description, execution, parameters }` - - `filename: string` + Hosted or BYOT tool search configuration for deferred tools. - The filename of the file cited. + - `type: "tool_search"` - - `index: number` + The type of the tool. Always `tool_search`. - The index of the file in the list of files. + - `"tool_search"` - - `type: "file_citation"` + - `description: optional string` - The citation type. Always `file_citation`. + Description shown to the model for a client-executed tool search tool. - - `"file_citation"` + - `execution: optional "server" or "client"` - - `URLCitation object { end_index, start_index, title, 2 more }` + Whether tool search is executed by the server or by the client. - - `end_index: number` + - `"server"` - The index of the last character of the citation in the message. + - `"client"` - - `start_index: number` + - `parameters: optional unknown` - The index of the first character of the citation in the message. + Parameter schema for a client-executed tool search tool. - - `title: string` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - The title of the cited resource. + 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: "url_citation"` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - The citation type. Always `url_citation`. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `"url_citation"` + - `"web_search_preview"` - - `url: string` + - `"web_search_preview_2025_03_11"` - The URL of the cited resource. + - `search_content_types: optional array of "text" or "image"` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + - `"text"` - - `container_id: string` + - `"image"` - The ID of the container. + - `search_context_size: optional "low" or "medium" or "high"` - - `end_index: number` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - The index of the last character of the citation in the message. + - `"low"` - - `file_id: string` + - `"medium"` - The ID of the container file. + - `"high"` - - `filename: string` + - `user_location: optional object { type, city, country, 2 more }` - The filename of the container file cited. + The user's location. - - `start_index: number` + - `type: "approximate"` - The index of the first character of the citation in the message. + The type of location approximation. Always `approximate`. - - `type: "container_file_citation"` + - `"approximate"` - The citation type. Always `container_file_citation`. + - `city: optional string` - - `"container_file_citation"` + Free text input for the city of the user, e.g. `San Francisco`. - - `type: "multi_agent_call_output"` + - `country: optional string` - The item type. Always `multi_agent_call_output`. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"multi_agent_call_output"` + - `region: optional string` - - `id: optional string` + Free text input for the region of the user, e.g. `California`. - The unique ID of this multi-agent call output. + - `timezone: optional string` - - `agent: optional object { agent_name }` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The agent that produced this item. + - `ApplyPatch object { type, allowed_callers }` - - `agent_name: string` + Allows the assistant to create, delete, or update files using unified diffs. - The canonical name of the agent that produced this item. + - `type: "apply_patch"` - - `ToolSearchCall object { arguments, type, id, 4 more }` + The type of the tool. Always `apply_patch`. - - `arguments: unknown` + - `"apply_patch"` - The arguments supplied to the tool search call. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "tool_search_call"` + The tool invocation context(s). - The item type. Always `tool_search_call`. + - `"direct"` - - `"tool_search_call"` + - `"programmatic"` - - `id: optional string` + - `type: "tool_search_output"` - The unique ID of this tool search call. + The type of the item. Always `tool_search_output`. + + - `"tool_search_output"` - `agent: optional object { agent_name }` @@ -42181,33 +42993,39 @@ Learn when and how to compact long-running conversations in the [conversation st The canonical name of the agent that produced this item. - - `call_id: optional string` + - `created_by: optional string` - The unique ID of the tool search call generated by the model. + The identifier of the actor that created the item. - - `execution: optional "server" or "client"` + - `AdditionalTools object { id, role, tools, 2 more }` - Whether tool search was executed by the server or by the client. + - `id: string` - - `"server"` + The unique ID of the additional tools item. - - `"client"` + - `role: "unknown" or "user" or "assistant" or 5 more` - - `status: optional "in_progress" or "completed" or "incomplete"` + The role that provided the additional tools. - The status of the tool search call. + - `"unknown"` - - `"in_progress"` + - `"user"` - - `"completed"` + - `"assistant"` - - `"incomplete"` + - `"system"` - - `ToolSearchOutput object { tools, type, id, 4 more }` + - `"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 loaded tool definitions returned by the tool search output. + The additional tool definitions made available at this item. - `Function object { name, parameters, strict, 5 more }` @@ -42728,40 +43546,8 @@ Learn when and how to compact long-running conversations in the [conversation st - `BetaContainerNetworkPolicyDisabled object { type }` - - `type: "disabled"` - - Disable outbound network access. Always `disabled`. - - - `"disabled"` - - `BetaContainerNetworkPolicyAllowlist 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 BetaContainerNetworkPolicyDomainSecret` - - 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`. @@ -42942,128 +43728,10 @@ Learn when and how to compact long-running conversations in the [conversation st - `BetaContainerAuto 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 BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - Network access policy for the container. - - - `BetaContainerNetworkPolicyDisabled object { type }` - - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - - `skills: optional array of BetaSkillReference or BetaInlineSkill` - - An optional list of skills referenced by id or inline data. - - - `BetaSkillReference 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. - - - `BetaInlineSkill object { description, name, source, type }` - - - `description: string` - - The description of the skill. - - - `name: string` - - The name of the skill. - - - `source: BetaInlineSkillSource` - - 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"` - - `BetaLocalEnvironment object { type, skills }` - - `type: "local"` - - Use a local computer environment. - - - `"local"` - - - `skills: optional array of BetaLocalSkill` - - 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. - - `BetaContainerReference 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) @@ -43348,15 +44016,11 @@ Learn when and how to compact long-running conversations in the [conversation st - `"programmatic"` - - `type: "tool_search_output"` - - The item type. Always `tool_search_output`. - - - `"tool_search_output"` + - `type: "additional_tools"` - - `id: optional string` + The type of the item. Always `additional_tools`. - The unique ID of this tool search output. + - `"additional_tools"` - `agent: optional object { agent_name }` @@ -43366,6299 +44030,4010 @@ Learn when and how to compact long-running conversations in the [conversation st The canonical name of the agent that produced this item. - - `call_id: optional string` - - The unique ID of the tool search call generated by the model. + - `Compaction object { id, encrypted_content, type, 2 more }` - - `execution: optional "server" or "client"` + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - Whether tool search was executed by the server or by the client. + - `id: string` - - `"server"` + The unique ID of the compaction item. - - `"client"` + - `encrypted_content: string` - - `status: optional "in_progress" or "completed" or "incomplete"` + The encrypted content that was produced by compaction. - The status of the tool search output. + - `type: "compaction"` - - `"in_progress"` + The type of the item. Always `compaction`. - - `"completed"` + - `"compaction"` - - `"incomplete"` + - `agent: optional object { agent_name }` - - `AdditionalTools object { role, tools, type, 2 more }` + The agent that produced this item. - - `role: "developer"` + - `agent_name: string` - The role that provided the additional tools. Only `developer` is supported. + The canonical name of the agent that produced this item. - - `"developer"` + - `created_by: optional string` - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + The identifier of the actor that created the item. - A list of additional tools made available at this item. + - `ImageGenerationCall object { id, result, status, 2 more }` - - `Function object { name, parameters, strict, 5 more }` + An image generation request made by 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 image generation call. - The name of the function to call. + - `result: string` - - `parameters: map[unknown]` + The generated image encoded in base64. - A JSON schema object describing the parameters of the function. + - `status: "in_progress" or "completed" or "generating" or "failed"` - - `strict: boolean` + The status of the image generation call. - Whether strict parameter validation is enforced for this function tool. + - `"in_progress"` - - `type: "function"` + - `"completed"` - The type of the function tool. Always `function`. + - `"generating"` - - `"function"` + - `"failed"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "image_generation_call"` - The tool invocation context(s). + The type of the image generation call. Always `image_generation_call`. - - `"direct"` + - `"image_generation_call"` - - `"programmatic"` + - `agent: optional object { agent_name }` - - `defer_loading: optional boolean` + The agent that produced this item. - Whether this function is deferred and loaded via tool search. + - `agent_name: string` - - `description: optional string` + The canonical name of the agent that produced this item. - A description of the function. Used by the model to determine whether or not to call the function. + - `CodeInterpreterCall object { id, code, container_id, 4 more }` - - `output_schema: optional map[unknown]` + A tool call to run code. - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `id: string` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + The unique ID of the code interpreter tool call. - 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). + - `code: string` - - `type: "file_search"` + The code to run, or null if not available. - The type of the file search tool. Always `file_search`. + - `container_id: string` - - `"file_search"` + The ID of the container used to run the code. - - `vector_store_ids: array of string` + - `outputs: array of object { logs, type } or object { type, url }` - The IDs of the vector stores to search. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `filters: optional object { key, type, value } or object { filters, type }` + - `Logs object { logs, type }` - A filter to apply. + The logs output from the code interpreter. - - `ComparisonFilter object { key, type, value }` + - `logs: string` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The logs output from the code interpreter. - - `key: string` + - `type: "logs"` - The key to compare against the value. + The type of the output. Always `logs`. - - `type: "eq" or "ne" or "gt" or 5 more` + - `"logs"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `Image object { type, url }` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + The image output from the code interpreter. - - `"eq"` + - `type: "image"` - - `"ne"` + The type of the output. Always `image`. - - `"gt"` + - `"image"` - - `"gte"` + - `url: string` - - `"lt"` + The URL of the image output from the code interpreter. - - `"lte"` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - `"in"` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `"nin"` + - `"in_progress"` - - `value: string or number or boolean or array of string or number` + - `"completed"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `"incomplete"` - - `string` + - `"interpreting"` - - `number` + - `"failed"` - - `boolean` + - `type: "code_interpreter_call"` - - `array of string or number` + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `string` + - `"code_interpreter_call"` - - `number` + - `agent: optional object { agent_name }` - - `CompoundFilter object { filters, type }` + The agent that produced this item. - Combine multiple filters using `and` or `or`. + - `agent_name: string` - - `filters: array of object { key, type, value } or unknown` + The canonical name of the agent that produced this item. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `LocalShellCall object { id, action, call_id, 3 more }` - - `ComparisonFilter object { key, type, value }` + A tool call to run a command on the local shell. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `id: string` - - `key: string` + The unique ID of the local shell call. - The key to compare against the value. + - `action: object { command, env, type, 3 more }` - - `type: "eq" or "ne" or "gt" or 5 more` + Execute a shell command on the server. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `command: array of string` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + The command to run. - - `"eq"` + - `env: map[string]` - - `"ne"` + Environment variables to set for the command. - - `"gt"` + - `type: "exec"` - - `"gte"` + The type of the local shell action. Always `exec`. - - `"lt"` + - `"exec"` - - `"lte"` + - `timeout_ms: optional number` - - `"in"` + Optional timeout in milliseconds for the command. - - `"nin"` + - `user: optional string` - - `value: string or number or boolean or array of string or number` + Optional user to run the command as. - The value to compare against the attribute key; supports string, number, or boolean types. + - `working_directory: optional string` - - `string` + Optional working directory to run the command in. - - `number` + - `call_id: string` - - `boolean` + The unique ID of the local shell tool call generated by the model. - - `array of string or number` + - `status: "in_progress" or "completed" or "incomplete"` - - `string` + The status of the local shell call. - - `number` + - `"in_progress"` - - `unknown` + - `"completed"` - - `type: "and" or "or"` + - `"incomplete"` - Type of operation: `and` or `or`. + - `type: "local_shell_call"` - - `"and"` + The type of the local shell call. Always `local_shell_call`. - - `"or"` + - `"local_shell_call"` - - `max_num_results: optional number` + - `agent: optional object { agent_name }` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + The agent that produced this item. - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `agent_name: string` - Ranking options for search. + The canonical name of the agent that produced this item. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `LocalShellCallOutput object { id, output, type, 2 more }` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + The output of a local shell tool call. - - `embedding_weight: number` + - `id: string` - The weight of the embedding in the reciprocal ranking fusion. + The unique ID of the local shell tool call generated by the model. - - `text_weight: number` + - `output: string` - The weight of the text in the reciprocal ranking fusion. + A JSON string of the output of the local shell tool call. - - `ranker: optional "auto" or "default-2024-11-15"` + - `type: "local_shell_call_output"` - The ranker to use for the file search. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `"auto"` + - `"local_shell_call_output"` - - `"default-2024-11-15"` + - `agent: optional object { agent_name }` - - `score_threshold: optional number` + The agent that produced this item. - 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. + - `agent_name: string` - - `Computer object { type }` + The canonical name of the agent that produced this item. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `status: optional "in_progress" or "completed" or "incomplete"` - - `type: "computer"` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - The type of the computer tool. Always `computer`. + - `"in_progress"` - - `"computer"` + - `"completed"` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `"incomplete"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `ShellCall object { id, action, call_id, 6 more }` - - `display_height: number` + A tool call that executes one or more shell commands in a managed environment. - The height of the computer display. + - `id: string` - - `display_width: number` + The unique ID of the shell tool call. Populated when this item is returned via API. - The width of the computer display. + - `action: object { commands, max_output_length, timeout_ms }` - - `environment: "windows" or "mac" or "linux" or 2 more` + The shell commands and limits that describe how to run the tool call. - The type of computer environment to control. + - `commands: array of string` - - `"windows"` + - `max_output_length: number` - - `"mac"` + Optional maximum number of characters to return from each command. - - `"linux"` + - `timeout_ms: number` - - `"ubuntu"` + Optional timeout in milliseconds for the commands. - - `"browser"` + - `call_id: string` - - `type: "computer_use_preview"` + The unique ID of the shell tool call generated by the model. - The type of the computer use tool. Always `computer_use_preview`. + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - - `"computer_use_preview"` + Represents the use of a local environment to perform shell actions. - - `WebSearch object { type, filters, search_context_size, user_location }` + - `BetaResponseLocalEnvironment object { type }` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + Represents the use of a local environment to perform shell actions. - - `type: "web_search" or "web_search_2025_08_26"` + - `type: "local"` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + The environment type. Always `local`. - - `"web_search"` + - `"local"` - - `"web_search_2025_08_26"` + - `BetaResponseContainerReference object { container_id, type }` - - `filters: optional object { allowed_domains }` + Represents a container created with /v1/containers. - Filters for the search. + - `container_id: string` - - `allowed_domains: optional array of string` + - `type: "container_reference"` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + The environment type. Always `container_reference`. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `"container_reference"` - - `search_context_size: optional "low" or "medium" or "high"` + - `status: "in_progress" or "completed" or "incomplete"` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `"low"` + - `"in_progress"` - - `"medium"` + - `"completed"` - - `"high"` + - `"incomplete"` - - `user_location: optional object { city, country, region, 2 more }` + - `type: "shell_call"` - The approximate location of the user. + The type of the item. Always `shell_call`. - - `city: optional string` + - `"shell_call"` - Free text input for the city of the user, e.g. `San Francisco`. + - `agent: optional object { agent_name }` - - `country: optional string` + The agent that produced this item. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `agent_name: string` - - `region: optional string` + The canonical name of the agent that produced this item. - Free text input for the region of the user, e.g. `California`. + - `caller: optional object { type } or object { caller_id, type }` - - `timezone: optional string` + The execution context that produced this tool call. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `Direct object { type }` - - `type: optional "approximate"` + - `type: "direct"` - The type of location approximation. Always `approximate`. + - `"direct"` - - `"approximate"` + - `Program object { caller_id, type }` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `caller_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 call ID of the program item that produced this tool call. - - `server_label: string` + - `type: "program"` - A label for this MCP server, used to identify it in tool calls. + - `"program"` - - `type: "mcp"` + - `created_by: optional string` - The type of the MCP tool. Always `mcp`. + The ID of the entity that created this tool call. - - `"mcp"` + - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + The output of a shell tool call that was emitted. - The tool invocation context(s). + - `id: string` - - `"direct"` + The unique ID of the shell call output. Populated when this item is returned via API. - - `"programmatic"` + - `call_id: string` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + The unique ID of the shell tool call generated by the model. - List of allowed tool names or a filter object. + - `max_output_length: number` - - `McpAllowedTools = array of string` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - A string array of allowed tool names + - `output: array of object { outcome, stderr, stdout, created_by }` - - `McpToolFilter object { read_only, tool_names }` + An array of shell call output contents - A filter object to specify which tools are allowed. + - `outcome: object { type } or object { exit_code, type }` - - `read_only: optional boolean` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - 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. + - `Timeout object { type }` - - `tool_names: optional array of string` + Indicates that the shell call exceeded its configured time limit. - List of allowed tool names. + - `type: "timeout"` - - `authorization: optional string` + The outcome type. Always `timeout`. - 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. + - `"timeout"` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `Exit object { exit_code, type }` - 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). + Indicates that the shell commands finished and returned an exit code. - Currently supported `connector_id` values are: + - `exit_code: 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` + Exit code from the shell process. - - `"connector_dropbox"` + - `type: "exit"` - - `"connector_gmail"` + The outcome type. Always `exit`. - - `"connector_googlecalendar"` + - `"exit"` - - `"connector_googledrive"` + - `stderr: string` - - `"connector_microsoftteams"` + The standard error output that was captured. - - `"connector_outlookcalendar"` + - `stdout: string` - - `"connector_outlookemail"` + The standard output that was captured. - - `"connector_sharepoint"` + - `created_by: optional string` - - `defer_loading: optional boolean` + The identifier of the actor that created the item. - Whether this MCP tool is deferred and discovered via tool search. + - `status: "in_progress" or "completed" or "incomplete"` - - `headers: optional map[string]` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `"in_progress"` - - `require_approval: optional object { always, never } or "always" or "never"` + - `"completed"` - Specify which of the MCP server's tools require approval. + - `"incomplete"` - - `McpToolApprovalFilter object { always, never }` + - `type: "shell_call_output"` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + The type of the shell call output. Always `shell_call_output`. - - `always: optional object { read_only, tool_names }` + - `"shell_call_output"` - A filter object to specify which tools are allowed. + - `agent: optional object { agent_name }` - - `read_only: optional boolean` + The agent that produced this item. - 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. + - `agent_name: string` - - `tool_names: optional array of string` + The canonical name of the agent that produced this item. - List of allowed tool names. + - `caller: optional object { type } or object { caller_id, type }` - - `never: optional object { read_only, tool_names }` + The execution context that produced this tool call. - A filter object to specify which tools are allowed. + - `Direct object { type }` - - `read_only: optional boolean` + - `type: "direct"` - 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"` - - `tool_names: optional array of string` + - `Program object { caller_id, type }` - List of allowed tool names. + - `caller_id: string` - - `McpToolApprovalSetting = "always" or "never"` + The call ID of the program item that produced this tool call. - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `type: "program"` - - `"always"` + - `"program"` - - `"never"` + - `created_by: optional string` - - `server_description: optional string` + The identifier of the actor that created the item. - Optional description of the MCP server, used to provide more context. + - `ApplyPatchCall object { id, call_id, operation, 5 more }` - - `server_url: optional string` + A tool call that applies file diffs by creating, deleting, or updating files. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `id: string` - - `tunnel_id: optional string` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - 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. + - `call_id: string` - - `CodeInterpreter object { container, type, allowed_callers }` + The unique ID of the apply patch tool call generated by the model. - A tool that runs Python code to help generate a response to a prompt. + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + - `CreateFile object { diff, path, type }` - - `string` + Instruction describing how to create a file via the apply_patch tool. - The container ID. + - `diff: string` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + Diff to apply. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `path: string` - - `type: "auto"` + Path of the file to create. - Always `auto`. + - `type: "create_file"` - - `"auto"` + Create a new file with the provided diff. - - `file_ids: optional array of string` + - `"create_file"` - An optional list of uploaded files to make available to your code. + - `DeleteFile object { path, type }` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + Instruction describing how to delete a file via the apply_patch tool. - The memory limit for the code interpreter container. + - `path: string` - - `"1g"` + Path of the file to delete. - - `"4g"` + - `type: "delete_file"` - - `"16g"` + Delete the specified file. - - `"64g"` + - `"delete_file"` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `UpdateFile object { diff, path, type }` - Network access policy for the container. + Instruction describing how to update a file via the apply_patch tool. - - `BetaContainerNetworkPolicyDisabled object { type }` + - `diff: string` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + Diff to apply. - - `type: "code_interpreter"` + - `path: string` - The type of the code interpreter tool. Always `code_interpreter`. + Path of the file to update. - - `"code_interpreter"` + - `type: "update_file"` - - `allowed_callers: optional array of "direct" or "programmatic"` + Update an existing file with the provided diff. - The tool invocation context(s). + - `"update_file"` - - `"direct"` + - `status: "in_progress" or "completed"` - - `"programmatic"` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `ProgrammaticToolCalling object { type }` + - `"in_progress"` - - `type: "programmatic_tool_calling"` + - `"completed"` - The type of the tool. Always `programmatic_tool_calling`. + - `type: "apply_patch_call"` - - `"programmatic_tool_calling"` + The type of the item. Always `apply_patch_call`. - - `ImageGeneration object { type, action, background, 9 more }` + - `"apply_patch_call"` - A tool that generates images using the GPT image models. + - `agent: optional object { agent_name }` - - `type: "image_generation"` + The agent that produced this item. - The type of the image generation tool. Always `image_generation`. + - `agent_name: string` - - `"image_generation"` + The canonical name of the agent that produced this item. - - `action: optional "generate" or "edit" or "auto"` + - `caller: optional object { type } or object { caller_id, type }` - Whether to generate a new image or edit an existing image. Default: `auto`. + The execution context that produced this tool call. - - `"generate"` + - `Direct object { type }` - - `"edit"` + - `type: "direct"` - - `"auto"` + - `"direct"` - - `background: optional "transparent" or "opaque" or "auto"` + - `Program object { caller_id, type }` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + - `caller_id: string` - - `"transparent"` + The call ID of the program item that produced this tool call. - - `"opaque"` + - `type: "program"` - - `"auto"` + - `"program"` - - `input_fidelity: optional "high" or "low"` + - `created_by: optional string` - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + The ID of the entity that created this tool call. - - `"high"` + - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` - - `"low"` + The output emitted by an apply patch tool call. - - `input_image_mask: optional object { file_id, image_url }` + - `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 output. Populated when this item is returned via API. - - `file_id: optional string` + - `call_id: string` - File ID for the mask image. + The unique ID of the apply patch tool call generated by the model. - - `image_url: optional string` + - `status: "completed" or "failed"` - Base64-encoded mask image. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"completed"` - The image generation model to use. Default: `gpt-image-1`. + - `"failed"` - - `string` + - `type: "apply_patch_call_output"` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + The type of the item. Always `apply_patch_call_output`. - The image generation model to use. Default: `gpt-image-1`. + - `"apply_patch_call_output"` - - `"gpt-image-1"` + - `agent: optional object { agent_name }` - - `"gpt-image-1-mini"` + The agent that produced this item. - - `"gpt-image-1.5"` + - `agent_name: string` - - `moderation: optional "auto" or "low"` + The canonical name of the agent that produced this item. - Moderation level for the generated image. Default: `auto`. + - `caller: optional object { type } or object { caller_id, type }` - - `"auto"` + The execution context that produced this tool call. - - `"low"` + - `Direct object { type }` - - `output_compression: optional number` + - `type: "direct"` - Compression level for the output image. Default: 100. + - `"direct"` - - `output_format: optional "png" or "webp" or "jpeg"` + - `Program object { caller_id, type }` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `caller_id: string` - - `"png"` + The call ID of the program item that produced this tool call. - - `"webp"` + - `type: "program"` - - `"jpeg"` + - `"program"` - - `partial_images: optional number` + - `created_by: optional string` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The ID of the entity that created this tool call output. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `output: optional string` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + Optional textual output returned by the apply patch tool. - - `"low"` + - `McpCall object { id, arguments, name, 7 more }` - - `"medium"` + An invocation of a tool on an MCP server. - - `"high"` + - `id: string` - - `"auto"` + The unique ID of the tool call. - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `arguments: 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`. + A JSON string of the arguments passed to the tool. - - `string` + - `name: string` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The name of the tool that was run. - 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`. + - `server_label: string` - - `"1024x1024"` + The label of the MCP server running the tool. - - `"1024x1536"` + - `type: "mcp_call"` - - `"1536x1024"` + The type of the item. Always `mcp_call`. - - `"auto"` + - `"mcp_call"` - - `LocalShell object { type }` + - `agent: optional object { agent_name }` - A tool that allows the model to execute shell commands in a local environment. + The agent that produced this item. - - `type: "local_shell"` + - `agent_name: string` - The type of the local shell tool. Always `local_shell`. + The canonical name of the agent that produced this item. - - `"local_shell"` + - `approval_request_id: optional string` - - `Shell object { type, allowed_callers, environment }` + 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 tool that allows the model to execute shell commands. + - `error: optional string` - - `type: "shell"` + The error from the tool call, if any. - The type of the shell tool. Always `shell`. + - `output: optional string` - - `"shell"` + The output from the tool call. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - The tool invocation context(s). + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `"direct"` + - `"in_progress"` - - `"programmatic"` + - `"completed"` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `"incomplete"` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `"calling"` - - `BetaLocalEnvironment object { type, skills }` + - `"failed"` - - `BetaContainerReference object { container_id, type }` + - `McpListTools object { id, server_label, tools, 3 more }` - - `Custom object { name, type, allowed_callers, 3 more }` + A list of tools available on an MCP server. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `id: string` - - `name: string` + The unique ID of the list. - The name of the custom tool, used to identify it in tool calls. + - `server_label: string` - - `type: "custom"` + The label of the MCP server. - The type of the custom tool. Always `custom`. + - `tools: array of object { input_schema, name, annotations, description }` - - `"custom"` + 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 tool should be deferred and discovered via tool search. + 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 object { type } or object { definition, syntax, type }` + - `type: "mcp_list_tools"` - The input format for the custom tool. Default is unconstrained text. + The type of the item. Always `mcp_list_tools`. - - `Text object { type }` + - `"mcp_list_tools"` - Unconstrained free-form text. + - `agent: optional object { agent_name }` - - `type: "text"` + The agent that produced this item. - Unconstrained text format. Always `text`. + - `agent_name: string` - - `"text"` + The canonical name of the agent that produced this item. - - `Grammar object { definition, syntax, type }` + - `error: optional string` - A grammar defined by the user. + Error message if the server could not list tools. - - `definition: string` + - `McpApprovalRequest object { id, arguments, name, 3 more }` - The grammar definition. + A request for human approval of a tool invocation. - - `syntax: "lark" or "regex"` + - `id: string` - The syntax of the grammar definition. One of `lark` or `regex`. + The unique ID of the approval request. - - `"lark"` + - `arguments: string` - - `"regex"` + A JSON string of arguments for the tool. - - `type: "grammar"` + - `name: string` - Grammar format. Always `grammar`. + The name of the tool to run. - - `"grammar"` + - `server_label: string` - - `Namespace object { description, name, tools, type }` + The label of the MCP server making the request. - Groups function/custom tools under a shared namespace. + - `type: "mcp_approval_request"` - - `description: string` + The type of the item. Always `mcp_approval_request`. - A description of the namespace shown to the model. + - `"mcp_approval_request"` - - `name: string` + - `agent: optional object { agent_name }` - The namespace name used in tool calls (for example, `crm`). + The agent that produced this item. - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `agent_name: string` - The function/custom tools available inside this namespace. + The canonical name of the agent that produced this item. - - `Function object { name, type, allowed_callers, 5 more }` + - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` - - `name: string` + A response to an MCP approval request. - - `type: "function"` + - `id: string` - - `"function"` + The unique ID of the approval response - - `allowed_callers: optional array of "direct" or "programmatic"` + - `approval_request_id: string` - The tool invocation context(s). + The ID of the approval request being answered. - - `"direct"` + - `approve: boolean` - - `"programmatic"` + Whether the request was approved. - - `defer_loading: optional boolean` + - `type: "mcp_approval_response"` - Whether this function should be deferred and discovered via tool search. + The type of the item. Always `mcp_approval_response`. - - `description: optional string` + - `"mcp_approval_response"` - - `output_schema: optional map[unknown]` + - `agent: optional object { agent_name }` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + The agent that produced this item. - - `parameters: optional unknown` + - `agent_name: string` - - `strict: optional boolean` + The canonical name of the agent that produced this 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. + - `reason: optional string` - - `Custom object { name, type, allowed_callers, 3 more }` + Optional reason for the decision. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `CustomToolCall object { call_id, input, name, 5 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. + - `agent: optional object { agent_name }` - - `format: optional object { type } or object { definition, syntax, type }` + The agent that produced this item. - The input format for the custom tool. Default is unconstrained text. + - `agent_name: string` - - `Text object { type }` + The canonical name of the agent that produced this item. - 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 custom tool being called. - - `type: "grammar"` + - `CustomToolCallOutput object { id, call_id, output, 5 more }` - Grammar format. Always `grammar`. + - `id: string` - - `"grammar"` + The unique ID of the custom tool call output item. - - `type: "namespace"` + - `call_id: string` - The type of the tool. Always `namespace`. + The call ID, used to map this custom tool call output to a custom tool call. - - `"namespace"` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `ToolSearch object { type, description, execution, parameters }` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - Hosted or BYOT tool search configuration for deferred tools. + - `StringOutput = string` - - `type: "tool_search"` + A string of the output of the custom tool call. - The type of the tool. Always `tool_search`. + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `"tool_search"` + Text, image, or file output of the custom tool call. - - `description: optional string` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - Description shown to the model for a client-executed tool search tool. + A text input to the model. - - `execution: optional "server" or "client"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - Whether tool search is executed by the server or by the client. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"server"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `"client"` + A file input to the model. - - `parameters: optional unknown` + - `status: "in_progress" or "completed" or "incomplete"` - Parameter schema for a client-executed tool search tool. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `"in_progress"` - 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). + - `"completed"` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `"incomplete"` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `type: "custom_tool_call_output"` - - `"web_search_preview"` + The type of the custom tool call output. Always `custom_tool_call_output`. - - `"web_search_preview_2025_03_11"` + - `"custom_tool_call_output"` - - `search_content_types: optional array of "text" or "image"` + - `agent: optional object { agent_name }` - - `"text"` + The agent that produced this item. - - `"image"` + - `agent_name: string` - - `search_context_size: optional "low" or "medium" or "high"` + The canonical name of the agent that produced this 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. + - `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"` - - `user_location: optional object { type, city, country, 2 more }` + The caller type. Always `direct`. - The user's location. + - `"direct"` - - `type: "approximate"` + - `Program object { caller_id, type }` - The type of location approximation. Always `approximate`. + - `caller_id: string` - - `"approximate"` + The call ID of the program item that produced this tool call. - - `city: optional string` + - `type: "program"` - Free text input for the city of the user, e.g. `San Francisco`. + The caller type. Always `program`. - - `country: optional string` + - `"program"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `created_by: optional string` - - `region: optional string` + The identifier of the actor that created the item. - Free text input for the region of the user, e.g. `California`. + - `parallel_tool_calls: boolean` - - `timezone: optional string` + Whether to allow the model to run tool calls in parallel. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `temperature: number` - - `ApplyPatch object { type, allowed_callers }` + 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. - Allows the assistant to create, delete, or update files using unified diffs. + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - - `type: "apply_patch"` + 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 type of the tool. Always `apply_patch`. + - `BetaToolChoiceOptions = "none" or "auto" or "required"` - - `"apply_patch"` + Controls which (if any) tool is called by the model. - - `allowed_callers: optional array of "direct" or "programmatic"` + `none` means the model will not call any tool and instead generates a message. - The tool invocation context(s). + `auto` means the model can pick between generating a message or calling one or + more tools. - - `"direct"` + `required` means the model must call one or more tools. - - `"programmatic"` + - `"none"` - - `type: "additional_tools"` + - `"auto"` - The item type. Always `additional_tools`. + - `"required"` - - `"additional_tools"` + - `BetaToolChoiceAllowed object { mode, tools, type }` - - `id: optional string` + Constrains the tools available to the model to a pre-defined set. - The unique ID of this additional tools item. + - `mode: "auto" or "required"` - - `agent: optional object { agent_name }` + Constrains the tools available to the model to a pre-defined set. - The agent that produced this item. + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `agent_name: string` + `required` requires the model to call one or more of the allowed tools. - The canonical name of the agent that produced this item. + - `"auto"` - - `Reasoning object { id, summary, type, 4 more }` + - `"required"` - 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). + - `tools: array of map[unknown]` - - `id: string` + A list of tool definitions that the model should be allowed to call. - The unique identifier of the reasoning content. + For the Responses API, the list of tool definitions might look like: - - `summary: array of object { text, type }` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - Reasoning summary content. + - `type: "allowed_tools"` - - `text: string` + Allowed tool configuration type. Always `allowed_tools`. - A summary of the reasoning output from the model so far. + - `"allowed_tools"` - - `type: "summary_text"` + - `BetaToolChoiceTypes object { type }` - The type of the object. Always `summary_text`. + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](/docs/guides/tools). - - `"summary_text"` + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` - - `type: "reasoning"` + The type of hosted tool the model should to use. Learn more about + [built-in tools](/docs/guides/tools). - The type of the object. Always `reasoning`. + Allowed values are: - - `"reasoning"` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `agent: optional object { agent_name }` + - `"file_search"` - The agent that produced this item. + - `"web_search_preview"` - - `agent_name: string` + - `"computer"` - The canonical name of the agent that produced this item. + - `"computer_use_preview"` - - `content: optional array of object { text, type }` + - `"computer_use"` - Reasoning text content. + - `"web_search_preview_2025_03_11"` - - `text: string` + - `"image_generation"` - The reasoning text from the model. + - `"code_interpreter"` - - `type: "reasoning_text"` + - `BetaToolChoiceFunction object { name, type }` - The type of the reasoning text. Always `reasoning_text`. + Use this option to force the model to call a specific function. - - `"reasoning_text"` + - `name: string` - - `encrypted_content: optional string` + The name of the function to call. - 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: "function"` - - `status: optional "in_progress" or "completed" or "incomplete"` + For function calling, the type is always `function`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"function"` - - `"in_progress"` + - `BetaToolChoiceMcp object { server_label, type, name }` - - `"completed"` + Use this option to force the model to call a specific tool on a remote MCP server. - - `"incomplete"` + - `server_label: string` - - `Compaction object { encrypted_content, type, id, agent }` + The label of the MCP server to use. - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + - `type: "mcp"` - - `encrypted_content: string` + For MCP tools, the type is always `mcp`. - The encrypted content of the compaction summary. + - `"mcp"` - - `type: "compaction"` + - `name: optional string` - The type of the item. Always `compaction`. + The name of the tool to call on the server. - - `"compaction"` + - `BetaToolChoiceCustom object { name, type }` - - `id: optional string` + Use this option to force the model to call a specific custom tool. - The ID of the compaction item. + - `name: string` - - `agent: optional object { agent_name }` + The name of the custom tool to call. - The agent that produced this item. + - `type: "custom"` - - `agent_name: string` + For custom tool calling, the type is always `custom`. - The canonical name of the agent that produced this item. + - `"custom"` - - `ImageGenerationCall object { id, result, status, 2 more }` + - `BetaSpecificProgrammaticToolCallingParam object { type }` - An image generation request made by the model. + - `type: "programmatic_tool_calling"` - - `id: string` + The tool to call. Always `programmatic_tool_calling`. - The unique ID of the image generation call. + - `"programmatic_tool_calling"` - - `result: string` + - `BetaToolChoiceApplyPatch object { type }` - The generated image encoded in base64. + Forces the model to call the apply_patch tool when executing a tool call. - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `type: "apply_patch"` - The status of the image generation call. + The tool to call. Always `apply_patch`. - - `"in_progress"` + - `"apply_patch"` - - `"completed"` + - `BetaToolChoiceShell object { type }` - - `"generating"` + Forces the model to call the shell tool when a tool call is required. - - `"failed"` + - `type: "shell"` - - `type: "image_generation_call"` + The tool to call. Always `shell`. - The type of the image generation call. Always `image_generation_call`. + - `"shell"` - - `"image_generation_call"` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - - `agent: optional object { agent_name }` + 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 agent that produced this item. + We support the following categories of tools: - - `agent_name: string` + - **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. - The canonical name of the agent that produced this item. + - `Function object { name, parameters, strict, 5 more }` - - `CodeInterpreterCall object { id, code, container_id, 4 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). - A tool call to run code. + - `name: string` - - `id: string` + The name of the function to call. - The unique ID of the code interpreter tool call. + - `parameters: map[unknown]` - - `code: string` + A JSON schema object describing the parameters of the function. - The code to run, or null if not available. + - `strict: boolean` - - `container_id: string` + Whether strict parameter validation is enforced for this function tool. - The ID of the container used to run the code. + - `type: "function"` - - `outputs: array of object { logs, type } or object { type, url }` + The type of the function tool. Always `function`. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `"function"` - - `Logs object { logs, type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - The logs output from the code interpreter. + The tool invocation context(s). - - `logs: string` + - `"direct"` - The logs output from the code interpreter. + - `"programmatic"` - - `type: "logs"` + - `defer_loading: optional boolean` - The type of the output. Always `logs`. + Whether this function is deferred and loaded via tool search. - - `"logs"` + - `description: optional string` - - `Image object { type, url }` + A description of the function. Used by the model to determine whether or not to call the function. - The image output from the code interpreter. + - `output_schema: optional map[unknown]` - - `type: "image"` + A JSON schema object describing the JSON value encoded in string outputs for this function. - The type of the output. Always `image`. + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `"image"` + 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). - - `url: string` + - `type: "file_search"` - The URL of the image output from the code interpreter. + The type of the file search tool. Always `file_search`. - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `"file_search"` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `vector_store_ids: array of string` - - `"in_progress"` + The IDs of the vector stores to search. - - `"completed"` + - `filters: optional object { key, type, value } or object { filters, type }` - - `"incomplete"` + A filter to apply. - - `"interpreting"` + - `ComparisonFilter object { key, type, value }` - - `"failed"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `type: "code_interpreter_call"` + - `key: string` - The type of the code interpreter tool call. Always `code_interpreter_call`. + The key to compare against the value. - - `"code_interpreter_call"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `agent: optional object { agent_name }` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The agent that produced this item. + - `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 - - `agent_name: string` + - `"eq"` - The canonical name of the agent that produced this item. + - `"ne"` - - `LocalShellCall object { id, action, call_id, 3 more }` + - `"gt"` - A tool call to run a command on the local shell. + - `"gte"` - - `id: string` + - `"lt"` - The unique ID of the local shell call. + - `"lte"` - - `action: object { command, env, type, 3 more }` + - `"in"` - Execute a shell command on the server. + - `"nin"` - - `command: array of string` + - `value: string or number or boolean or array of string or number` - The command to run. + The value to compare against the attribute key; supports string, number, or boolean types. - - `env: map[string]` + - `string` - Environment variables to set for the command. + - `number` - - `type: "exec"` + - `boolean` - The type of the local shell action. Always `exec`. + - `array of string or number` - - `"exec"` + - `string` - - `timeout_ms: optional number` + - `number` - Optional timeout in milliseconds for the command. + - `CompoundFilter object { filters, type }` - - `user: optional string` + Combine multiple filters using `and` or `or`. - Optional user to run the command as. + - `filters: array of object { key, type, value } or unknown` - - `working_directory: optional string` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - Optional working directory to run the command in. + - `ComparisonFilter object { key, type, value }` - - `call_id: string` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The unique ID of the local shell tool call generated by the model. + - `key: string` - - `status: "in_progress" or "completed" or "incomplete"` + The key to compare against the value. - The status of the local shell call. + - `type: "eq" or "ne" or "gt" or 5 more` - - `"in_progress"` + 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 - - `"incomplete"` + - `"eq"` - - `type: "local_shell_call"` + - `"ne"` - The type of the local shell call. Always `local_shell_call`. + - `"gt"` - - `"local_shell_call"` + - `"gte"` - - `agent: optional object { agent_name }` + - `"lt"` - The agent that produced this item. + - `"lte"` - - `agent_name: string` + - `"in"` - The canonical name of the agent that produced this item. + - `"nin"` - - `LocalShellCallOutput object { id, output, type, 2 more }` + - `value: string or number or boolean or array of string or number` - The output of a local shell tool call. + The value to compare against the attribute key; supports string, number, or boolean types. - - `id: string` + - `string` - The unique ID of the local shell tool call generated by the model. + - `number` - - `output: string` + - `boolean` - A JSON string of the output of the local shell tool call. + - `array of string or number` - - `type: "local_shell_call_output"` + - `string` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `number` - - `"local_shell_call_output"` + - `unknown` - - `agent: optional object { agent_name }` + - `type: "and" or "or"` - The agent that produced this item. + Type of operation: `and` or `or`. - - `agent_name: string` + - `"and"` - The canonical name of the agent that produced this item. + - `"or"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `max_num_results: optional number` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `"in_progress"` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `"completed"` + Ranking options for search. - - `"incomplete"` + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `ShellCall object { action, call_id, type, 5 more }` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - A tool representing a request to execute one or more shell commands. + - `embedding_weight: number` - - `action: object { commands, max_output_length, timeout_ms }` + The weight of the embedding in the reciprocal ranking fusion. - The shell commands and limits that describe how to run the tool call. + - `text_weight: number` - - `commands: array of string` + The weight of the text in the reciprocal ranking fusion. - Ordered shell commands for the execution environment to run. + - `ranker: optional "auto" or "default-2024-11-15"` - - `max_output_length: optional number` + The ranker to use for the file search. - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `"auto"` - - `timeout_ms: optional number` + - `"default-2024-11-15"` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `score_threshold: optional number` - - `call_id: string` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - The unique ID of the shell tool call generated by the model. + - `Computer object { type }` - - `type: "shell_call"` + 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 item. Always `shell_call`. + - `type: "computer"` - - `"shell_call"` + The type of the computer tool. Always `computer`. - - `id: optional string` + - `"computer"` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `agent: optional object { agent_name }` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The agent that produced this item. + - `display_height: number` - - `agent_name: string` + The height of the computer display. - The canonical name of the agent that produced this item. + - `display_width: number` - - `caller: optional object { type } or object { caller_id, type }` + The width of the computer display. - The execution context that produced this tool call. + - `environment: "windows" or "mac" or "linux" or 2 more` - - `Direct object { type }` + The type of computer environment to control. - - `type: "direct"` + - `"windows"` - The caller type. Always `direct`. + - `"mac"` - - `"direct"` + - `"linux"` - - `Program object { caller_id, type }` + - `"ubuntu"` - - `caller_id: string` + - `"browser"` - The call ID of the program item that produced this tool call. + - `type: "computer_use_preview"` - - `type: "program"` + The type of the computer use tool. Always `computer_use_preview`. - The caller type. Always `program`. + - `"computer_use_preview"` - - `"program"` + - `WebSearch object { type, filters, search_context_size, user_location }` - - `environment: optional BetaLocalEnvironment or BetaContainerReference` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - The environment to execute the shell commands in. + - `type: "web_search" or "web_search_2025_08_26"` - - `BetaLocalEnvironment object { type, skills }` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `BetaContainerReference object { container_id, type }` + - `"web_search"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"web_search_2025_08_26"` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `filters: optional object { allowed_domains }` - - `"in_progress"` + Filters for the search. - - `"completed"` + - `allowed_domains: optional array of string` - - `"incomplete"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `ShellCallOutput object { call_id, output, type, 5 more }` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - The streamed output items emitted by a shell tool call. + - `search_context_size: optional "low" or "medium" or "high"` - - `call_id: string` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - The unique ID of the shell tool call generated by the model. + - `"low"` - - `output: array of BetaResponseFunctionShellCallOutputContent` + - `"medium"` - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `"high"` - - `outcome: object { type } or object { exit_code, type }` + - `user_location: optional object { city, country, region, 2 more }` - The exit or timeout outcome associated with this shell call. + The approximate location of the user. - - `Timeout object { type }` + - `city: optional string` - Indicates that the shell call exceeded its configured time limit. + Free text input for the city of the user, e.g. `San Francisco`. - - `type: "timeout"` + - `country: optional string` - The outcome type. Always `timeout`. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"timeout"` + - `region: optional string` - - `Exit object { exit_code, type }` + Free text input for the region of the user, e.g. `California`. - Indicates that the shell commands finished and returned an exit code. + - `timezone: optional string` - - `exit_code: number` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The exit code returned by the shell process. + - `type: optional "approximate"` - - `type: "exit"` + The type of location approximation. Always `approximate`. - The outcome type. Always `exit`. + - `"approximate"` - - `"exit"` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `stderr: string` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - Captured stderr output for the shell call. + - `server_label: string` - - `stdout: string` + A label for this MCP server, used to identify it in tool calls. - Captured stdout output for the shell call. + - `type: "mcp"` - - `type: "shell_call_output"` + The type of the MCP tool. Always `mcp`. - The type of the item. Always `shell_call_output`. + - `"mcp"` - - `"shell_call_output"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `id: optional string` + The tool invocation context(s). - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `"direct"` - - `agent: optional object { agent_name }` + - `"programmatic"` - The agent that produced this item. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `agent_name: string` + List of allowed tool names or a filter object. - The canonical name of the agent that produced this item. + - `McpAllowedTools = array of string` - - `caller: optional object { type } or object { caller_id, type }` + A string array of allowed tool names - The execution context that produced this tool call. + - `McpToolFilter object { read_only, tool_names }` - - `Direct object { type }` + A filter object to specify which tools are allowed. - - `type: "direct"` + - `read_only: optional boolean` - The caller type. Always `direct`. + 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"` + - `tool_names: optional array of string` - - `Program object { caller_id, type }` + List of allowed tool names. - - `caller_id: string` + - `authorization: optional string` - The call ID of the program item that produced this tool call. + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - - `type: "program"` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - The caller type. Always `program`. + 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). - - `"program"` + Currently supported `connector_id` values are: - - `max_output_length: optional number` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - The maximum number of UTF-8 characters captured for this shell call's combined output. + - `"connector_dropbox"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"connector_gmail"` - The status of the shell call output. + - `"connector_googlecalendar"` - - `"in_progress"` + - `"connector_googledrive"` - - `"completed"` + - `"connector_microsoftteams"` - - `"incomplete"` + - `"connector_outlookcalendar"` - - `ApplyPatchCall object { call_id, operation, status, 4 more }` + - `"connector_outlookemail"` - A tool call representing a request to create, delete, or update files using diff patches. + - `"connector_sharepoint"` - - `call_id: string` + - `defer_loading: optional boolean` - The unique ID of the apply patch tool call generated by the model. + Whether this MCP tool is deferred and discovered via tool search. - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `headers: optional map[string]` - The specific create, delete, or update instruction for the apply_patch tool call. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `CreateFile object { diff, path, type }` + - `require_approval: optional object { always, never } or "always" or "never"` - Instruction for creating a new file via the apply_patch tool. + Specify which of the MCP server's tools require approval. - - `diff: string` + - `McpToolApprovalFilter object { always, never }` - Unified diff content to apply when creating the 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. - - `path: string` + - `always: optional object { read_only, tool_names }` - Path of the file to create relative to the workspace root. + A filter object to specify which tools are allowed. - - `type: "create_file"` + - `read_only: optional boolean` - The operation type. Always `create_file`. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `"create_file"` + - `tool_names: optional array of string` - - `DeleteFile object { path, type }` + List of allowed tool names. - Instruction for deleting an existing file via the apply_patch tool. + - `never: optional object { read_only, tool_names }` - - `path: string` + A filter object to specify which tools are allowed. - Path of the file to delete relative to the workspace root. + - `read_only: optional boolean` - - `type: "delete_file"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The operation type. Always `delete_file`. + - `tool_names: optional array of string` - - `"delete_file"` + List of allowed tool names. - - `UpdateFile object { diff, path, type }` + - `McpToolApprovalSetting = "always" or "never"` - Instruction for updating an existing file via the apply_patch tool. + 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. - - `diff: string` + - `"always"` - Unified diff content to apply to the existing file. + - `"never"` - - `path: string` + - `server_description: optional string` - Path of the file to update relative to the workspace root. + Optional description of the MCP server, used to provide more context. - - `type: "update_file"` + - `server_url: optional string` - The operation type. Always `update_file`. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `"update_file"` + - `tunnel_id: optional string` - - `status: "in_progress" or "completed"` + 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 status of the apply patch tool call. One of `in_progress` or `completed`. + - `CodeInterpreter object { container, type, allowed_callers }` - - `"in_progress"` + A tool that runs Python code to help generate a response to a prompt. - - `"completed"` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `type: "apply_patch_call"` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - The type of the item. Always `apply_patch_call`. + - `string` - - `"apply_patch_call"` + The container ID. - - `id: optional string` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `agent: optional object { agent_name }` + - `type: "auto"` - The agent that produced this item. + Always `auto`. - - `agent_name: string` + - `"auto"` - The canonical name of the agent that produced this item. + - `file_ids: optional array of string` - - `caller: optional object { type } or object { caller_id, type }` + An optional list of uploaded files to make available to your code. - The execution context that produced this tool call. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `Direct object { type }` + The memory limit for the code interpreter container. - - `type: "direct"` + - `"1g"` - The caller type. Always `direct`. + - `"4g"` - - `"direct"` + - `"16g"` - - `Program object { caller_id, type }` + - `"64g"` - - `caller_id: string` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - The call ID of the program item that produced this tool call. + Network access policy for the container. - - `type: "program"` + - `BetaContainerNetworkPolicyDisabled object { type }` - The caller type. Always `program`. + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `"program"` + - `type: "code_interpreter"` - - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` + The type of the code interpreter tool. Always `code_interpreter`. - The streamed output emitted by an apply patch tool call. + - `"code_interpreter"` - - `call_id: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The unique ID of the apply patch tool call generated by the model. + The tool invocation context(s). - - `status: "completed" or "failed"` + - `"direct"` - The status of the apply patch tool call output. One of `completed` or `failed`. + - `"programmatic"` - - `"completed"` + - `ProgrammaticToolCalling object { type }` - - `"failed"` + - `type: "programmatic_tool_calling"` - - `type: "apply_patch_call_output"` + The type of the tool. Always `programmatic_tool_calling`. - The type of the item. Always `apply_patch_call_output`. + - `"programmatic_tool_calling"` - - `"apply_patch_call_output"` + - `ImageGeneration object { type, action, background, 9 more }` - - `id: optional string` + A tool that generates images using the GPT image models. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `type: "image_generation"` - - `agent: optional object { agent_name }` + The type of the image generation tool. Always `image_generation`. - The agent that produced this item. + - `"image_generation"` - - `agent_name: string` + - `action: optional "generate" or "edit" or "auto"` - The canonical name of the agent that produced this item. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `caller: optional object { type } or object { caller_id, type }` + - `"generate"` - The execution context that produced this tool call. + - `"edit"` - - `Direct object { type }` + - `"auto"` - - `type: "direct"` + - `background: optional "transparent" or "opaque" or "auto"` - The caller type. Always `direct`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `"direct"` + - `"transparent"` - - `Program object { caller_id, type }` + - `"opaque"` - - `caller_id: string` + - `"auto"` - The call ID of the program item that produced this tool call. + - `input_fidelity: optional "high" or "low"` - - `type: "program"` + 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 caller type. Always `program`. + - `"high"` - - `"program"` + - `"low"` - - `output: optional string` + - `input_image_mask: optional object { file_id, image_url }` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `McpListTools object { id, server_label, tools, 3 more }` + - `file_id: optional string` - A list of tools available on an MCP server. + File ID for the mask image. - - `id: string` + - `image_url: optional string` - The unique ID of the list. + Base64-encoded mask image. - - `server_label: string` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The label of the MCP server. + The image generation model to use. Default: `gpt-image-1`. - - `tools: array of object { input_schema, name, annotations, description }` + - `string` - The tools available on the server. + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `input_schema: unknown` + The image generation model to use. Default: `gpt-image-1`. - The JSON schema describing the tool's input. + - `"gpt-image-1"` - - `name: string` + - `"gpt-image-1-mini"` - The name of the tool. + - `"gpt-image-1.5"` - - `annotations: optional unknown` + - `moderation: optional "auto" or "low"` - Additional annotations about the tool. + Moderation level for the generated image. Default: `auto`. - - `description: optional string` + - `"auto"` - The description of the tool. + - `"low"` - - `type: "mcp_list_tools"` + - `output_compression: optional number` - The type of the item. Always `mcp_list_tools`. + Compression level for the output image. Default: 100. - - `"mcp_list_tools"` + - `output_format: optional "png" or "webp" or "jpeg"` - - `agent: optional object { agent_name }` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The agent that produced this item. + - `"png"` - - `agent_name: string` + - `"webp"` - The canonical name of the agent that produced this item. + - `"jpeg"` - - `error: optional string` + - `partial_images: optional number` - Error message if the server could not list tools. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `McpApprovalRequest object { id, arguments, name, 3 more }` + - `quality: optional "low" or "medium" or "high" or "auto"` - A request for human approval of a tool invocation. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `id: string` + - `"low"` - The unique ID of the approval request. + - `"medium"` - - `arguments: string` + - `"high"` - A JSON string of arguments for the tool. + - `"auto"` - - `name: string` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - The name of the tool to run. + 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`. - - `server_label: string` + - `string` - The label of the MCP server making the request. + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `type: "mcp_approval_request"` + 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_request`. + - `"1024x1024"` - - `"mcp_approval_request"` + - `"1024x1536"` - - `agent: optional object { agent_name }` + - `"1536x1024"` - The agent that produced this item. + - `"auto"` - - `agent_name: string` + - `LocalShell object { type }` - The canonical name of the agent that produced this item. + A tool that allows the model to execute shell commands in a local environment. - - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` + - `type: "local_shell"` - A response to an MCP approval request. + The type of the local shell tool. Always `local_shell`. - - `approval_request_id: string` + - `"local_shell"` - The ID of the approval request being answered. + - `Shell object { type, allowed_callers, environment }` - - `approve: boolean` + A tool that allows the model to execute shell commands. - Whether the request was approved. + - `type: "shell"` - - `type: "mcp_approval_response"` + The type of the shell tool. Always `shell`. - The type of the item. Always `mcp_approval_response`. + - `"shell"` - - `"mcp_approval_response"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `id: optional string` + The tool invocation context(s). - The unique ID of the approval response + - `"direct"` - - `agent: optional object { agent_name }` + - `"programmatic"` - The agent that produced this item. + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `agent_name: string` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - The canonical name of the agent that produced this item. + - `BetaLocalEnvironment object { type, skills }` - - `reason: optional string` + - `BetaContainerReference object { container_id, type }` - Optional reason for the decision. + - `Custom object { name, type, allowed_callers, 3 more }` - - `McpCall object { id, arguments, name, 7 more }` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - An invocation of a tool 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 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"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `approval_request_id: optional string` + - `type: "custom"` - 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 type of the custom tool. Always `custom`. - - `error: optional string` + - `"custom"` - The error from the tool call, if any. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `output: optional string` + The tool invocation context(s). - The output from the tool call. + - `"direct"` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `"programmatic"` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `defer_loading: optional boolean` - - `"in_progress"` + Whether this tool should be deferred and discovered via tool search. - - `"completed"` + - `description: optional string` - - `"incomplete"` + Optional description of the custom tool, used to provide more context. - - `"calling"` + - `format: optional object { type } or object { definition, syntax, type }` - - `"failed"` + The input format for the custom tool. Default is unconstrained text. - - `CustomToolCallOutput object { call_id, output, type, 3 more }` + - `Text object { type }` - The output of a custom tool call from your code, being sent back to the model. + Unconstrained free-form text. - - `call_id: string` + - `type: "text"` - The call ID, used to map this custom tool call output to a custom tool call. + Unconstrained text format. Always `text`. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `"text"` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `Grammar object { definition, syntax, type }` - - `StringOutput = string` + A grammar defined by the user. - A string of the output of the custom tool call. + - `definition: string` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The grammar definition. - Text, image, or file output of the custom tool call. + - `syntax: "lark" or "regex"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + The syntax of the grammar definition. One of `lark` or `regex`. - A text input to the model. + - `"lark"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `"regex"` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `type: "grammar"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + Grammar format. Always `grammar`. - A file input to the model. + - `"grammar"` - - `type: "custom_tool_call_output"` + - `Namespace object { description, name, tools, type }` - The type of the custom tool call output. Always `custom_tool_call_output`. + Groups function/custom tools under a shared namespace. - - `"custom_tool_call_output"` + - `description: string` - - `id: optional string` + A description of the namespace shown to the model. - The unique ID of the custom tool call output in the OpenAI platform. + - `name: string` - - `agent: optional object { agent_name }` + The namespace name used in tool calls (for example, `crm`). - The agent that produced this item. + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `agent_name: string` + The function/custom tools available inside this namespace. - The canonical name of the agent that produced this item. + - `Function object { name, type, allowed_callers, 5 more }` - - `caller: optional object { type } or object { caller_id, type }` + - `name: string` - The execution context that produced this tool call. + - `type: "function"` - - `Direct object { type }` + - `"function"` - - `type: "direct"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The caller type. Always `direct`. + The tool invocation context(s). - `"direct"` - - `Program object { caller_id, type }` - - - `caller_id: string` + - `"programmatic"` - The call ID of the program item that produced this tool call. + - `defer_loading: optional boolean` - - `type: "program"` + Whether this function should be deferred and discovered via tool search. - The caller type. Always `program`. + - `description: optional string` - - `"program"` + - `output_schema: optional map[unknown]` - - `CustomToolCall object { call_id, input, 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 call to a custom tool created by the model. + - `parameters: optional unknown` - - `call_id: string` + - `strict: optional boolean` - An identifier used to map this custom tool call to a tool call output. + 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. - - `input: string` + - `Custom object { name, type, allowed_callers, 3 more }` - The input for the custom 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 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. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` + The name of the custom tool, used to identify it in tool calls. - The canonical name of the agent that produced this item. + - `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 }` - - - `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. - - - `CompactionTrigger object { type, agent }` - - Compacts the current context. Must be the final input item. - - - `type: "compaction_trigger"` - - The type of the item. Always `compaction_trigger`. - - - `"compaction_trigger"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. + - `"programmatic"` - - `ItemReference object { id, agent, type }` + - `defer_loading: optional boolean` - An internal identifier for an item to reference. + Whether this tool should be deferred and discovered via tool search. - - `id: string` + - `description: optional string` - The ID of the item to reference. + Optional description of the custom tool, used to provide more context. - - `agent: optional object { agent_name }` + - `format: optional object { type } or object { definition, syntax, type }` - The agent that produced this item. + The input format for the custom tool. Default is unconstrained text. - - `agent_name: string` + - `Text object { type }` - The canonical name of the agent that produced this item. + Unconstrained free-form text. - - `type: optional "item_reference"` + - `type: "text"` - The type of item to reference. Always `item_reference`. + Unconstrained text format. Always `text`. - - `"item_reference"` + - `"text"` - - `Program object { id, call_id, code, 3 more }` + - `Grammar object { definition, syntax, type }` - - `id: string` + A grammar defined by the user. - The unique ID of this program item. + - `definition: string` - - `call_id: string` + The grammar definition. - The stable call ID of the program item. + - `syntax: "lark" or "regex"` - - `code: string` + The syntax of the grammar definition. One of `lark` or `regex`. - The JavaScript source executed by programmatic tool calling. + - `"lark"` - - `fingerprint: string` + - `"regex"` - Opaque program replay fingerprint that must be round-tripped. + - `type: "grammar"` - - `type: "program"` + Grammar format. Always `grammar`. - The item type. Always `program`. + - `"grammar"` - - `"program"` + - `type: "namespace"` - - `agent: optional object { agent_name }` + The type of the tool. Always `namespace`. - The agent that produced this item. + - `"namespace"` - - `agent_name: string` + - `ToolSearch object { type, description, execution, parameters }` - The canonical name of the agent that produced this item. + Hosted or BYOT tool search configuration for deferred tools. - - `ProgramOutput object { id, call_id, result, 3 more }` + - `type: "tool_search"` - - `id: string` + The type of the tool. Always `tool_search`. - The unique ID of this program output item. + - `"tool_search"` - - `call_id: string` + - `description: optional string` - The call ID of the program item. + Description shown to the model for a client-executed tool search tool. - - `result: string` + - `execution: optional "server" or "client"` - The result produced by the program item. + Whether tool search is executed by the server or by the client. - - `status: "completed" or "incomplete"` + - `"server"` - The terminal status of the program output. + - `"client"` - - `"completed"` + - `parameters: optional unknown` - - `"incomplete"` + Parameter schema for a client-executed tool search tool. - - `type: "program_output"` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - The item type. Always `program_output`. + This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). - - `"program_output"` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `agent: optional object { agent_name }` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The agent that produced this item. + - `"web_search_preview"` - - `agent_name: string` + - `"web_search_preview_2025_03_11"` - The canonical name of the agent that produced this item. + - `search_content_types: optional array of "text" or "image"` -- `instructions: optional string` + - `"text"` - 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. + - `"image"` -- `previous_response_id: optional string` + - `search_context_size: optional "low" or "medium" or "high"` - 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 level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. -- `prompt_cache_key: optional string` + - `"low"` - A key to use when reading from or writing to the prompt cache. + - `"medium"` -- `prompt_cache_options: optional object { mode, ttl }` + - `"high"` - 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. + - `user_location: optional object { type, city, country, 2 more }` - - `mode: optional "implicit" or "explicit"` + The user's location. - 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. + - `type: "approximate"` - - `"implicit"` + The type of location approximation. Always `approximate`. - - `"explicit"` + - `"approximate"` - - `ttl: optional "30m"` + - `city: 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. + Free text input for the city of the user, e.g. `San Francisco`. - - `"30m"` + - `country: optional string` -- `prompt_cache_retention: optional "in_memory" or "24h"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - How long to retain a prompt cache entry created by this request. + - `region: optional string` - - `"in_memory"` + Free text input for the region of the user, e.g. `California`. - - `"24h"` + - `timezone: optional string` -- `service_tier: optional "auto" or "default" or "flex" or "priority"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The service tier to use for this request. + - `ApplyPatch object { type, allowed_callers }` - - `"auto"` + Allows the assistant to create, delete, or update files using unified diffs. - - `"default"` + - `type: "apply_patch"` - - `"flex"` + The type of the tool. Always `apply_patch`. - - `"priority"` + - `"apply_patch"` -### Returns + - `allowed_callers: optional array of "direct" or "programmatic"` -- `BetaCompactedResponse object { id, created_at, object, 2 more }` + The tool invocation context(s). - - `id: string` + - `"direct"` - The unique identifier for the compacted response. + - `"programmatic"` - - `created_at: number` + - `top_p: number` - Unix timestamp (in seconds) when the compacted conversation was created. + 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. - - `object: "response.compaction"` + We generally recommend altering this or `temperature` but not both. - The object type. Always `response.compaction`. + - `background: optional boolean` - - `"response.compaction"` + Whether to run the model response in the background. + [Learn more](/docs/guides/background). - - `output: array of object { id, content, role, 4 more } or object { id, call_id, code, 3 more } or object { id, call_id, result, 3 more } or 28 more` + - `completed_at: optional number` - The compacted list of output items. + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - - `Message object { id, content, role, 4 more }` + - `conversation: optional object { id }` - A message to or from the model. + 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 message. - - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - - The content of the message - - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `text: string` - - The text input to the model. - - - `type: "input_text"` - - The type of the input item. Always `input_text`. - - - `"input_text"` - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `"explicit"` - - - `BetaResponseOutputText 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 }` + The unique ID of the conversation that this response was associated with. - A citation for a web resource used to generate a model response. + - `max_output_tokens: optional number` - - `end_index: 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). - The index of the last character of the URL citation in the message. + - `max_tool_calls: optional number` - - `start_index: 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. - The index of the first character of the URL citation in the message. + - `moderation: optional object { input, output }` - - `title: string` + Moderation results for the response input and output, if moderated completions were requested. - The title of the web resource. + - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - - `type: "url_citation"` + Moderation for the response input. - The type of the URL citation. Always `url_citation`. + - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` - - `"url_citation"` + A moderation result produced for the response input or output. - - `url: string` + - `categories: map[boolean]` - The URL of the web resource. + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + - `category_applied_input_types: map[array of "text" or "image"]` - A citation for a container file used to generate a model response. + Which modalities of input are reflected by the score for each category. - - `container_id: string` + - `"text"` - The ID of the container file. + - `"image"` - - `end_index: number` + - `category_scores: map[number]` - The index of the last character of the container file citation in the message. + A dictionary of moderation categories to scores. - - `file_id: string` + - `flagged: boolean` - The ID of the file. + A boolean indicating whether the content was flagged by any category. - - `filename: string` + - `model: string` - The filename of the container file cited. + The moderation model that produced this result. - - `start_index: number` + - `type: "moderation_result"` - The index of the first character of the container file citation in the message. + The object type, which was always `moderation_result` for successful moderation results. - - `type: "container_file_citation"` + - `"moderation_result"` - The type of the container file citation. Always `container_file_citation`. + - `Error object { code, message, type }` - - `"container_file_citation"` + An error produced while attempting moderation for the response input or output. - - `FilePath object { file_id, index, type }` + - `code: string` - A path to a file. + The error code. - - `file_id: string` + - `message: string` - The ID of the file. + The error message. - - `index: number` + - `type: "error"` - The index of the file in the list of files. + The object type, which was always `error` for moderation failures. - - `type: "file_path"` + - `"error"` - The type of the file path. Always `file_path`. + - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - - `"file_path"` + Moderation for the response output. - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `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. - - `top_logprobs: array of object { token, bytes, logprob }` + - `category_applied_input_types: map[array of "text" or "image"]` - - `token: string` + Which modalities of input are reflected by the score for each category. - - `bytes: array of number` + - `"text"` - - `logprob: number` + - `"image"` - - `text: string` + - `category_scores: map[number]` - The text output from the model. + A dictionary of moderation categories to scores. - - `type: "output_text"` + - `flagged: boolean` - The type of the output text. Always `output_text`. + A boolean indicating whether the content was flagged by any category. - - `"output_text"` + - `model: string` - - `Text object { text, type }` + The moderation model that produced this result. - A text content. + - `type: "moderation_result"` - - `text: string` + The object type, which was always `moderation_result` for successful moderation results. - - `type: "text"` + - `"moderation_result"` - - `"text"` + - `Error object { code, message, type }` - - `SummaryText object { text, type }` + An error produced while attempting moderation for the response input or output. - A summary text from the model. + - `code: string` - - `text: string` + The error code. - A summary of the reasoning output from the model so far. + - `message: string` - - `type: "summary_text"` + The error message. - The type of the object. Always `summary_text`. + - `type: "error"` - - `"summary_text"` + The object type, which was always `error` for moderation failures. - - `ReasoningText object { text, type }` + - `"error"` - Reasoning text from the model. + - `output_text: optional string` - - `text: 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. - The reasoning text from the model. + - `previous_response_id: optional string` - - `type: "reasoning_text"` + 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 reasoning text. Always `reasoning_text`. + - `prompt: optional BetaResponsePrompt` - - `"reasoning_text"` + Reference to a prompt template and its variables. + [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). - - `BetaResponseOutputRefusal object { refusal, type }` + - `id: string` - A refusal from the model. + The unique identifier of the prompt template to use. - - `refusal: string` + - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` - The refusal explanation from the model. + 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. - - `type: "refusal"` + - `string` - The type of the refusal. Always `refusal`. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `"refusal"` + A text input to the model. - `BetaResponseInputImage 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"` - - - `"high"` - - - `"auto"` - - - `"original"` - - - `type: "input_image"` - - The type of the input item. Always `input_image`. - - - `"input_image"` - - - `file_id: optional string` - - The ID of the file to be sent to the model. - - - `image_url: optional string` - - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `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"` - - - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` - - A screenshot of a computer. - - - `detail: "low" or "high" or "auto" or "original"` - - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `"low"` - - - `"high"` - - - `"auto"` - - - `"original"` - - - `file_id: string` - - The identifier of an uploaded file that contains the screenshot. - - - `image_url: string` - - The URL of the screenshot image. - - - `type: "computer_screenshot"` - - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - - `"computer_screenshot"` - - - `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"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. - - `type: "input_file"` + - `version: optional string` - The type of the input item. Always `input_file`. + Optional version of the prompt template. - - `"input_file"` + - `prompt_cache_key: optional string` - - `detail: optional "auto" or "low" or "high"` + 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 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`. + - `prompt_cache_options: optional object { mode, ttl }` - - `"auto"` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `"low"` + - `mode: "implicit" or "explicit"` - - `"high"` + Whether implicit prompt-cache breakpoints were enabled. - - `file_data: optional string` + - `"implicit"` - The content of the file to be sent to the model. + - `"explicit"` - - `file_id: optional string` + - `ttl: "30m"` - The ID of the file to be sent to the model. + The minimum lifetime applied to each cache breakpoint. - - `file_url: optional string` + - `"30m"` - The URL of the file to be sent to the model. + - `prompt_cache_retention: optional "in_memory" or "24h"` - - `filename: optional string` + Deprecated. Use `prompt_cache_options.ttl` instead. - The name of the file to be sent to the model. + 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. - - `prompt_cache_breakpoint: optional object { mode }` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - 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. + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `mode: "explicit"` + - `"in_memory"` - The breakpoint mode. Always `explicit`. + - `"24h"` - - `"explicit"` + - `reasoning: optional object { context, effort, generate_summary, 2 more }` - - `EncryptedContent object { encrypted_content, type }` + **gpt-5 and o-series models only** - Opaque encrypted content that Responses API decrypts inside trusted model execution. + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `encrypted_content: string` + - `context: optional "auto" or "current_turn" or "all_turns"` - Opaque encrypted content. + 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`. - - `type: "encrypted_content"` + When returned on a response, this is the effective reasoning context mode + used for the response. - The type of the input item. Always `encrypted_content`. + - `"auto"` - - `"encrypted_content"` + - `"current_turn"` - - `role: "unknown" or "user" or "assistant" or 5 more` + - `"all_turns"` - The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. + - `effort: optional "none" or "minimal" or "low" or 4 more` - - `"unknown"` + 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"` - - `"critic"` + - `"medium"` - - `"discriminator"` + - `"high"` - - `"developer"` + - `"xhigh"` - - `"tool"` + - `"max"` - - `status: "in_progress" or "completed" or "incomplete"` + - `generate_summary: optional "auto" or "concise" or "detailed"` - The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + **Deprecated:** use `summary` instead. - - `"in_progress"` + 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`. - - `"completed"` + - `"auto"` - - `"incomplete"` + - `"concise"` - - `type: "message"` + - `"detailed"` - The type of the message. Always set to `message`. + - `mode: optional string or "standard" or "pro"` - - `"message"` + Controls the reasoning execution mode for the request. - - `agent: optional object { agent_name }` + When returned on a response, this is the effective execution mode. - The agent that produced this item. + - `string` - - `agent_name: string` + - `"standard" or "pro"` - The canonical name of the agent that produced this item. + Controls the reasoning execution mode for the request. - - `phase: optional "commentary" or "final_answer"` + When returned on a response, this is the effective execution mode. - 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. + - `"standard"` - - `"commentary"` + - `"pro"` - - `"final_answer"` + - `summary: optional "auto" or "concise" or "detailed"` - - `Program object { id, call_id, code, 3 more }` + 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`. - - `id: string` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - The unique ID of the program item. + - `"auto"` - - `call_id: string` + - `"concise"` - The stable call ID of the program item. + - `"detailed"` - - `code: string` + - `safety_identifier: optional string` - The JavaScript source executed by 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). - - `fingerprint: string` + - `service_tier: optional "auto" or "default" or "flex" or 2 more` - Opaque program replay fingerprint that must be round-tripped. + Specifies the processing type used for serving the request. - - `type: "program"` + - 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 type of the item. Always `program`. + 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. - - `"program"` + - `"auto"` - - `agent: optional object { agent_name }` + - `"default"` - The agent that produced this item. + - `"flex"` - - `agent_name: string` + - `"scale"` - The canonical name of the agent that produced this item. + - `"priority"` - - `ProgramOutput object { id, call_id, result, 3 more }` + - `status: optional BetaResponseStatus` - - `id: string` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - The unique ID of the program output item. + - `"completed"` - - `call_id: string` + - `"failed"` - The call ID of the program item. + - `"in_progress"` - - `result: string` + - `"cancelled"` - The result produced by the program item. + - `"queued"` - - `status: "completed" or "incomplete"` + - `"incomplete"` - The terminal status of the program output item. + - `text: optional BetaResponseTextConfig` - - `"completed"` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `"incomplete"` + - [Text inputs and outputs](/docs/guides/text) + - [Structured Outputs](/docs/guides/structured-outputs) - - `type: "program_output"` + - `format: optional BetaResponseFormatTextConfig` - The type of the item. Always `program_output`. + An object specifying the format that the model must output. - - `"program_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). - - `agent: optional object { agent_name }` + The default format is `{ "type": "text" }` with no additional options. - The agent that produced this item. + **Not recommended for gpt-4o and newer models:** - - `agent_name: 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 canonical name of the agent that produced this item. + - `Text object { type }` - - `FunctionCall object { arguments, call_id, name, 6 more }` + Default response format. Used to generate text responses. - A tool call to run a function. See the - [function calling guide](/docs/guides/function-calling) for more information. + - `type: "text"` - - `arguments: string` + The type of response format being defined. Always `text`. - A JSON string of the arguments to pass to the function. + - `"text"` - - `call_id: string` + - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` - The unique ID of the function 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 function to run. + 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: "function_call"` + - `schema: map[unknown]` - The type of the function tool call. Always `function_call`. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `"function_call"` + - `type: "json_schema"` - - `id: optional string` + The type of response format being defined. Always `json_schema`. - The unique ID of the function tool call. + - `"json_schema"` - - `agent: optional object { agent_name }` + - `description: optional string` - The agent that produced this item. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `agent_name: string` + - `strict: optional boolean` - The canonical name of the agent that produced this item. + 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). - - `caller: optional object { type } or object { caller_id, type }` + - `JSONObject object { type }` - The execution context that produced this tool call. + 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. - - `Direct object { type }` + - `type: "json_object"` - - `type: "direct"` + The type of response format being defined. Always `json_object`. - - `"direct"` + - `"json_object"` - - `Program object { caller_id, type }` + - `verbosity: optional "low" or "medium" or "high"` - - `caller_id: string` + 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 call ID of the program item that produced this tool call. + - `"low"` - - `type: "program"` + - `"medium"` - - `"program"` + - `"high"` - - `namespace: optional string` + - `top_logprobs: optional number` - The namespace of the function to run. + 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. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `truncation: optional "auto" or "disabled"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The truncation strategy to use for the model response. - - `"in_progress"` + - `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. - - `"completed"` + - `"auto"` - - `"incomplete"` + - `"disabled"` - - `MultiAgentCall object { id, action, arguments, 3 more }` + - `usage: optional BetaResponseUsage` - - `id: string` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - The unique ID of the multi-agent call item. + - `input_tokens: number` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + The number of input tokens. - The multi-agent action to execute. + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` - - `"spawn_agent"` + A detailed breakdown of the input tokens. - - `"interrupt_agent"` + - `cache_write_tokens: number` - - `"list_agents"` + The number of input tokens that were written to the cache. - - `"send_message"` + - `cached_tokens: number` - - `"followup_task"` + The number of tokens that were retrieved from the cache. + [More on prompt caching](/docs/guides/prompt-caching). - - `"wait_agent"` + - `output_tokens: number` - - `arguments: string` + The number of output tokens. - The JSON string of arguments generated for the action. + - `output_tokens_details: object { reasoning_tokens }` - - `call_id: string` + A detailed breakdown of the output tokens. - The unique ID linking this call to its output. + - `reasoning_tokens: number` - - `type: "multi_agent_call"` + The number of reasoning tokens. - The type of the multi-agent call. Always `multi_agent_call`. + - `total_tokens: number` - - `"multi_agent_call"` + The total number of tokens used. - - `agent: optional object { agent_name }` + - `user: optional string` - The agent that produced this item. + 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). - - `agent_name: string` +### Example - The canonical name of the agent that produced this item. +```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" + }' +``` - - `MultiAgentCallOutput object { id, action, call_id, 3 more }` - - - `id: string` - - The unique ID of the multi-agent call output item. - - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - The multi-agent action that produced this result. - - - `"spawn_agent"` - - - `"interrupt_agent"` - - - `"list_agents"` - - - `"send_message"` - - - `"followup_task"` - - - `"wait_agent"` - - - `call_id: string` - - The unique ID of the multi-agent call. - - - `output: array of BetaResponseOutputText` - - Text output returned by the multi-agent action. - - - `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. - - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - - - `text: string` - - The text output from the model. - - - `type: "output_text"` - - The type of the output text. Always `output_text`. - - - `type: "multi_agent_call_output"` - - The type of the multi-agent result. Always `multi_agent_call_output`. - - - `"multi_agent_call_output"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `ToolSearchCall object { id, arguments, call_id, 5 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"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `created_by: optional string` - - The identifier of the actor that created the item. - - - `ToolSearchOutput object { id, call_id, execution, 5 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 }` - - 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 object { key, type, value } or object { filters, type }` - - 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 object { key, type, value } 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. - - - `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` - - - `unknown` - - - `type: "and" or "or"` - - Type of operation: `and` or `or`. - - - `"and"` - - - `"or"` - - - `max_num_results: optional number` - - The maximum number of results to return. This number should be between 1 and 50 inclusive. - - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - Ranking options for search. - - - `hybrid_search: optional object { embedding_weight, text_weight }` - - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - - `embedding_weight: number` - - The weight of the embedding in the reciprocal ranking fusion. - - - `text_weight: number` - - The weight of the text in the reciprocal ranking fusion. - - - `ranker: optional "auto" or "default-2024-11-15"` - - The ranker to use for the file search. - - - `"auto"` - - - `"default-2024-11-15"` - - - `score_threshold: optional number` - - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - - - `Computer object { type }` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `type: "computer"` - - The type of the computer tool. Always `computer`. - - - `"computer"` - - - `ComputerUsePreview object { display_height, display_width, environment, type }` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `display_height: number` - - The height of the computer display. - - - `display_width: number` - - The width of the computer display. - - - `environment: "windows" or "mac" or "linux" or 2 more` - - The type of computer environment to control. - - - `"windows"` - - - `"mac"` - - - `"linux"` - - - `"ubuntu"` - - - `"browser"` - - - `type: "computer_use_preview"` - - The type of the computer use tool. Always `computer_use_preview`. - - - `"computer_use_preview"` - - - `WebSearch object { type, filters, search_context_size, user_location }` - - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). - - - `type: "web_search" or "web_search_2025_08_26"` - - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - - `"web_search"` - - - `"web_search_2025_08_26"` - - - `filters: optional object { allowed_domains }` - - Filters for the search. - - - `allowed_domains: optional array of string` - - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. - - Example: `["pubmed.ncbi.nlm.nih.gov"]` - - - `search_context_size: optional "low" or "medium" or "high"` - - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - - `"low"` - - - `"medium"` - - - `"high"` - - - `user_location: optional object { city, country, region, 2 more }` - - The approximate location of the user. - - - `city: optional string` - - Free text input for the city of the user, e.g. `San Francisco`. - - - `country: optional string` - - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - - `region: optional string` - - Free text input for the region of the user, e.g. `California`. - - - `timezone: optional string` - - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - - `type: optional "approximate"` - - The type of location approximation. Always `approximate`. - - - `"approximate"` - - - `Mcp object { server_label, type, allowed_callers, 9 more }` - - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - - `server_label: string` - - A label for this MCP server, used to identify it in tool calls. - - - `type: "mcp"` - - The type of the MCP tool. Always `mcp`. - - - `"mcp"` - - - `allowed_callers: optional array of "direct" or "programmatic"` - - The tool invocation context(s). - - - `"direct"` - - - `"programmatic"` - - - `allowed_tools: optional array of string or object { read_only, tool_names }` - - List of allowed tool names or a filter object. - - - `McpAllowedTools = array of string` - - A string array of allowed tool names - - - `McpToolFilter object { read_only, tool_names }` - - A filter object to specify which tools are allowed. - - - `read_only: optional boolean` - - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. - - - `tool_names: optional array of string` - - List of allowed tool names. - - - `authorization: optional string` - - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. - - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). - - Currently supported `connector_id` values are: - - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` - - - `"connector_dropbox"` - - - `"connector_gmail"` - - - `"connector_googlecalendar"` - - - `"connector_googledrive"` - - - `"connector_microsoftteams"` - - - `"connector_outlookcalendar"` - - - `"connector_outlookemail"` - - - `"connector_sharepoint"` - - - `defer_loading: optional boolean` - - Whether this MCP tool is deferred and discovered via tool search. - - - `headers: optional map[string]` - - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. - - - `require_approval: optional object { always, never } or "always" or "never"` - - Specify which of the MCP server's tools require approval. - - - `McpToolApprovalFilter object { always, never }` - - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. - - - `always: optional object { read_only, tool_names }` - - A filter object to specify which tools are allowed. - - - `read_only: optional boolean` - - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. - - - `tool_names: optional array of string` - - List of allowed tool names. - - - `never: optional object { read_only, tool_names }` - - A filter object to specify which tools are allowed. - - - `read_only: optional boolean` - - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. - - - `tool_names: optional array of string` - - List of allowed tool names. - - - `McpToolApprovalSetting = "always" or "never"` - - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. - - - `"always"` - - - `"never"` - - - `server_description: optional string` - - Optional description of the MCP server, used to provide more context. - - - `server_url: optional string` - - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. - - - `tunnel_id: optional string` - - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. - - - `CodeInterpreter object { container, type, allowed_callers }` - - A tool that runs Python code to help generate a response to a prompt. - - - `container: string or object { type, file_ids, memory_limit, network_policy }` - - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. - - - `string` - - The container ID. - - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - - `type: "auto"` - - Always `auto`. - - - `"auto"` - - - `file_ids: optional array of string` - - An optional list of uploaded files to make available to your code. - - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - The memory limit for the code interpreter container. - - - `"1g"` - - - `"4g"` - - - `"16g"` - - - `"64g"` - - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - Network access policy for the container. - - - `BetaContainerNetworkPolicyDisabled object { type }` - - - `type: "disabled"` - - Disable outbound network access. Always `disabled`. - - - `"disabled"` - - - `BetaContainerNetworkPolicyAllowlist 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 BetaContainerNetworkPolicyDomainSecret` - - Optional domain-scoped secrets for allowlisted domains. - - - `domain: string` - - The domain associated with the secret. - - - `name: string` - - The name of the secret to inject for the domain. - - - `value: string` - - The secret value to inject for the domain. - - - `type: "code_interpreter"` - - The type of the code interpreter tool. Always `code_interpreter`. - - - `"code_interpreter"` - - - `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 BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - - `BetaContainerAuto 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 BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - Network access policy for the container. - - - `BetaContainerNetworkPolicyDisabled object { type }` - - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - - `skills: optional array of BetaSkillReference or BetaInlineSkill` - - An optional list of skills referenced by id or inline data. - - - `BetaSkillReference 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. - - - `BetaInlineSkill object { description, name, source, type }` - - - `description: string` - - The description of the skill. - - - `name: string` - - The name of the skill. - - - `source: BetaInlineSkillSource` - - 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"` - - - `BetaLocalEnvironment object { type, skills }` - - - `type: "local"` - - Use a local computer environment. - - - `"local"` - - - `skills: optional array of BetaLocalSkill` - - 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. - - - `BetaContainerReference 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 object { type } or object { definition, syntax, type }` - - 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 object { type } or object { definition, syntax, type }` - - 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"` - - - `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 type of the item. Always `tool_search_output`. - - - `"tool_search_output"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `created_by: optional string` - - The identifier of the actor that created the item. - - - `AdditionalTools object { id, role, tools, 2 more }` - - - `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. - - - `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 object { key, type, value } or object { filters, type }` - - 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 object { key, type, value } 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. - - - `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` - - - `unknown` - - - `type: "and" or "or"` - - Type of operation: `and` or `or`. - - - `"and"` - - - `"or"` - - - `max_num_results: optional number` - - The maximum number of results to return. This number should be between 1 and 50 inclusive. - - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - Ranking options for search. - - - `hybrid_search: optional object { embedding_weight, text_weight }` - - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - - `embedding_weight: number` - - The weight of the embedding in the reciprocal ranking fusion. - - - `text_weight: number` - - The weight of the text in the reciprocal ranking fusion. - - - `ranker: optional "auto" or "default-2024-11-15"` - - The ranker to use for the file search. - - - `"auto"` - - - `"default-2024-11-15"` - - - `score_threshold: optional number` - - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - - - `Computer object { type }` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `type: "computer"` - - The type of the computer tool. Always `computer`. - - - `"computer"` - - - `ComputerUsePreview object { display_height, display_width, environment, type }` - - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - - `display_height: number` - - The height of the computer display. - - - `display_width: number` - - The width of the computer display. - - - `environment: "windows" or "mac" or "linux" or 2 more` - - The type of computer environment to control. - - - `"windows"` - - - `"mac"` - - - `"linux"` - - - `"ubuntu"` - - - `"browser"` - - - `type: "computer_use_preview"` - - The type of the computer use tool. Always `computer_use_preview`. - - - `"computer_use_preview"` - - - `WebSearch object { type, filters, search_context_size, user_location }` - - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). - - - `type: "web_search" or "web_search_2025_08_26"` - - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - - `"web_search"` - - - `"web_search_2025_08_26"` - - - `filters: optional object { allowed_domains }` - - Filters for the search. - - - `allowed_domains: optional array of string` - - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. - - Example: `["pubmed.ncbi.nlm.nih.gov"]` - - - `search_context_size: optional "low" or "medium" or "high"` - - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - - `"low"` - - - `"medium"` - - - `"high"` - - - `user_location: optional object { city, country, region, 2 more }` - - The approximate location of the user. - - - `city: optional string` - - Free text input for the city of the user, e.g. `San Francisco`. - - - `country: optional string` - - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - - `region: optional string` - - Free text input for the region of the user, e.g. `California`. - - - `timezone: optional string` - - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - - `type: optional "approximate"` - - The type of location approximation. Always `approximate`. - - - `"approximate"` - - - `Mcp object { server_label, type, allowed_callers, 9 more }` - - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - - `server_label: string` - - A label for this MCP server, used to identify it in tool calls. - - - `type: "mcp"` - - The type of the MCP tool. Always `mcp`. - - - `"mcp"` - - - `allowed_callers: optional array of "direct" or "programmatic"` - - The tool invocation context(s). - - - `"direct"` - - - `"programmatic"` - - - `allowed_tools: optional array of string or object { read_only, tool_names }` - - List of allowed tool names or a filter object. - - - `McpAllowedTools = array of string` - - A string array of allowed tool names - - - `McpToolFilter object { read_only, tool_names }` - - A filter object to specify which tools are allowed. - - - `read_only: optional boolean` - - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. - - - `tool_names: optional array of string` - - List of allowed tool names. - - - `authorization: optional string` - - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. - - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). - - Currently supported `connector_id` values are: - - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` - - - `"connector_dropbox"` - - - `"connector_gmail"` - - - `"connector_googlecalendar"` - - - `"connector_googledrive"` - - - `"connector_microsoftteams"` - - - `"connector_outlookcalendar"` - - - `"connector_outlookemail"` - - - `"connector_sharepoint"` - - - `defer_loading: optional boolean` - - Whether this MCP tool is deferred and discovered via tool search. - - - `headers: optional map[string]` - - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. - - - `require_approval: optional object { always, never } or "always" or "never"` - - Specify which of the MCP server's tools require approval. - - - `McpToolApprovalFilter object { always, never }` - - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. - - - `always: optional object { read_only, tool_names }` - - A filter object to specify which tools are allowed. - - - `read_only: optional boolean` - - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. - - - `tool_names: optional array of string` - - List of allowed tool names. - - - `never: optional object { read_only, tool_names }` - - A filter object to specify which tools are allowed. - - - `read_only: optional boolean` - - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. - - - `tool_names: optional array of string` - - List of allowed tool names. - - - `McpToolApprovalSetting = "always" or "never"` - - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. - - - `"always"` - - - `"never"` - - - `server_description: optional string` - - Optional description of the MCP server, used to provide more context. - - - `server_url: optional string` - - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. - - - `tunnel_id: optional string` - - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. - - - `CodeInterpreter object { container, type, allowed_callers }` - - A tool that runs Python code to help generate a response to a prompt. - - - `container: string or object { type, file_ids, memory_limit, network_policy }` - - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. - - - `string` - - The container ID. - - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - - `type: "auto"` - - Always `auto`. - - - `"auto"` - - - `file_ids: optional array of string` - - An optional list of uploaded files to make available to your code. - - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - The memory limit for the code interpreter container. - - - `"1g"` - - - `"4g"` - - - `"16g"` - - - `"64g"` - - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - Network access policy for the container. - - - `BetaContainerNetworkPolicyDisabled object { type }` - - - `BetaContainerNetworkPolicyAllowlist 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 BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - - `BetaLocalEnvironment object { type, skills }` - - - `BetaContainerReference 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 object { type } or object { definition, syntax, type }` - - 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 object { type } or object { definition, syntax, type }` - - 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"` - - - `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: "additional_tools"` - - The type of the item. Always `additional_tools`. - - - `"additional_tools"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `AgentMessage object { id, author, content, 3 more }` - - - `id: string` - - The unique ID of the agent message. - - - `author: string` - - The sending agent identity. - - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - - Encrypted content sent between agents. - - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `BetaResponseOutputText object { annotations, logprobs, text, type }` - - A text output from the model. - - - `Text object { text, type }` - - A text content. - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `SummaryText object { text, type }` - - A summary text from the model. - - - `text: string` - - A summary of the reasoning output from the model so far. - - - `type: "summary_text"` - - The type of the object. Always `summary_text`. - - - `"summary_text"` - - - `ReasoningText object { text, type }` - - Reasoning text from the model. - - - `text: string` - - The reasoning text from the model. - - - `type: "reasoning_text"` - - The type of the reasoning text. Always `reasoning_text`. - - - `"reasoning_text"` - - - `BetaResponseOutputRefusal object { refusal, type }` - - A refusal from the model. - - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](/docs/guides/vision). - - - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` - - A screenshot of a computer. - - - `detail: "low" or "high" or "auto" or "original"` - - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `"low"` - - - `"high"` - - - `"auto"` - - - `"original"` - - - `file_id: string` - - The identifier of an uploaded file that contains the screenshot. - - - `image_url: string` - - The URL of the screenshot image. - - - `type: "computer_screenshot"` - - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - - `"computer_screenshot"` - - - `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"` - - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - A file input to the model. - - - `EncryptedContent object { encrypted_content, type }` - - Opaque encrypted content that Responses API decrypts inside trusted model execution. - - - `encrypted_content: string` - - Opaque encrypted content. - - - `type: "encrypted_content"` - - The type of the input item. Always `encrypted_content`. - - - `"encrypted_content"` - - - `recipient: string` - - The destination agent identity. - - - `type: "agent_message"` - - The type of the item. Always `agent_message`. - - - `"agent_message"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `FunctionCallOutput object { call_id, output, type, 4 more }` - - The output of a function tool call. - - - `call_id: string` - - The unique ID of the function tool call generated by the model. - - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - The output from the function call generated by your code. - Can be a string or an list of output content. - - - `StringOutput = string` - - A string of the output of the function call. - - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - Text, image, or file output of the function call. - - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](/docs/guides/vision). - - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - A file input to the model. - - - `type: "function_call_output"` - - The type of the function tool call output. Always `function_call_output`. - - - `"function_call_output"` - - - `id: optional string` - - The unique ID of the function tool call output. Populated when this item - is returned via API. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `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"` - - - `FileSearchCall object { id, queries, status, 3 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"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `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. - - - `WebSearchCall object { id, action, status, 2 more }` - - The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. - - - `id: string` - - The unique ID of the web search tool call. - - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). - - - `Search object { type, queries, query, sources }` - - Action type "search" - Performs a web search query. - - - `type: "search"` - - The action type. - - - `"search"` - - - `queries: optional array of string` - - The search queries. - - - `query: optional string` - - The search query. - - - `sources: optional array of object { type, url }` - - The sources used in the search. - - - `type: "url"` - - The type of source. Always `url`. - - - `"url"` - - - `url: string` - - The URL of the source. - - - `OpenPage object { type, url }` - - Action type "open_page" - Opens a specific URL from search results. - - - `type: "open_page"` - - The action type. - - - `"open_page"` - - - `url: optional string` - - The URL opened by the model. - - - `FindInPage object { pattern, type, url }` - - Action type "find_in_page": Searches for a pattern within a loaded page. - - - `pattern: string` - - The pattern or text to search for within the page. - - - `type: "find_in_page"` - - The action type. - - - `"find_in_page"` - - - `url: string` - - The URL of the page searched for the pattern. - - - `status: "in_progress" or "searching" or "completed" or "failed"` - - The status of the web search tool call. - - - `"in_progress"` - - - `"searching"` - - - `"completed"` - - - `"failed"` - - - `type: "web_search_call"` - - The type of the web search tool call. Always `web_search_call`. - - - `"web_search_call"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `ImageGenerationCall object { id, result, status, 2 more }` - - An image generation request made by the model. - - - `id: string` - - The unique ID of the image generation call. - - - `result: string` - - The generated image encoded in base64. - - - `status: "in_progress" or "completed" or "generating" or "failed"` - - The status of the image generation call. - - - `"in_progress"` - - - `"completed"` - - - `"generating"` - - - `"failed"` - - - `type: "image_generation_call"` - - The type of the image generation call. Always `image_generation_call`. - - - `"image_generation_call"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `ComputerCall object { id, call_id, pending_safety_checks, 5 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 BetaComputerAction` - - 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 +#### Response - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } +```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 + } ] - ``` - - - `x: number` - - The x-coordinate. - - - `y: number` - - The y-coordinate. - - - `type: "drag"` - - Specifies the event type. For a drag action, this property is always set to `drag`. - - - `"drag"` - - - `keys: optional array of string` - - The keys being held while dragging the mouse. - - - `Keypress object { keys, type }` - - A collection of keypresses the model would like to perform. - - - `keys: array of string` - - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - - `type: "keypress"` - - Specifies the event type. For a keypress action, this property is always set to `keypress`. - - - `"keypress"` - - - `Move object { type, x, y, keys }` - - A mouse move action. - - - `type: "move"` - - Specifies the event type. For a move action, this property is always set to `move`. - - - `"move"` - - - `x: number` - - The x-coordinate to move to. - - - `y: number` - - The y-coordinate to move to. - - - `keys: optional array of string` - - The keys being held while moving the mouse. - - - `Screenshot object { type }` - - A screenshot action. - - - `type: "screenshot"` - - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - - `"screenshot"` - - - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - A scroll action. - - - `scroll_x: number` - - The horizontal scroll distance. - - - `scroll_y: number` - - The vertical scroll distance. - - - `type: "scroll"` - - Specifies the event type. For a scroll action, this property is always set to `scroll`. - - - `"scroll"` - - - `x: number` - - The x-coordinate where the scroll occurred. - - - `y: number` - - The y-coordinate where the scroll occurred. - - - `keys: optional array of string` - - The keys being held while scrolling. - - - `Type object { text, type }` - - An action to type in text. - - - `text: string` - - The text to type. - - - `type: "type"` - - Specifies the event type. For a type action, this property is always set to `type`. - - - `"type"` - - - `Wait object { type }` - - A wait action. - - - `type: "wait"` - - Specifies the event type. For a wait action, this property is always set to `wait`. - - - `"wait"` - - - `actions: optional BetaComputerActionList` - - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. - - - `Click object { button, type, x, 2 more }` - - A click action. - - - `DoubleClick object { keys, type, x, y }` - - A double click action. - - - `Drag object { path, type, keys }` - - A drag action. - - - `Keypress object { keys, type }` - - A collection of keypresses the model would like to perform. - - - `Move object { type, x, y, keys }` - - A mouse move action. - - - `Screenshot object { type }` - - A screenshot action. - - - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - A scroll action. - - - `Type object { text, type }` - - An action to type in text. - - - `Wait object { type }` - - A wait action. + } + ], + "text": "text", + "type": "output_text" + } + ], + "role": "assistant", + "status": "in_progress", + "type": "message", + "agent": { + "agent_name": "agent_name" + }, + "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" +} +``` - - `agent: optional object { agent_name }` +### File input - The agent that produced this item. +```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" + } + ] + } + ] + }' +``` - - `agent_name: string` +#### Response - The canonical name of the agent that produced this item. +```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": {} +} +``` - - `ComputerCallOutput object { id, call_id, output, 5 more }` +### File search - - `id: string` +```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?" + }' +``` - The unique ID of the computer call tool output. +#### Response - - `call_id: string` +```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": {} +} +``` - The ID of the computer tool call that produced the output. +### Functions - - `output: BetaResponseComputerToolCallOutputScreenshot` +```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" + }' +``` - A computer screenshot image used with the computer use tool. +#### Response - - `type: "computer_screenshot"` +```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": {} +} +``` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. +### Image input - - `"computer_screenshot"` +```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" + } + ] + } + ] + }' +``` - - `file_id: optional string` +#### Response - The identifier of an uploaded file that contains the screenshot. +```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": {} +} +``` - - `image_url: optional string` +### Reasoning - The URL of the screenshot image. +```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" + } + }' +``` - - `status: "completed" or "incomplete" or "failed" or "in_progress"` +#### Response - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. +```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": {} +} +``` - - `"completed"` +### Streaming - - `"incomplete"` +```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 + }' +``` - - `"failed"` +#### Response - - `"in_progress"` +```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":{}}} - - `type: "computer_call_output"` +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":{}}} - The type of the computer tool call output. Always `computer_call_output`. +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":[]}} - - `"computer_call_output"` +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":[]}} - - `acknowledged_safety_checks: optional array of object { id, code, message }` +event: response.output_text.delta +data: {"type":"response.output_text.delta","item_id":"msg_67c9fdcf37fc8190ba82116e33fb28c507b8b0ad4e5eb654","output_index":0,"content_index":0,"delta":"Hi"} - The safety checks reported by the API that have been acknowledged by the - developer. +... - - `id: string` +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 ID of the pending safety check. +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: optional string` +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":[]}]}} - The type of the pending safety check. +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":{}}} +``` - - `message: optional string` +### Text input - Details about the pending safety check. +```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." + }' +``` - - `agent: optional object { agent_name }` +#### Response - The agent that produced this item. +```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": {} +} +``` - - `agent_name: string` +### Web search - The canonical name of the agent that produced this item. +```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?" + }' +``` - - `created_by: optional string` +#### Response - The identifier of the actor that created the item. +```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": {} +} +``` - - `Reasoning object { id, summary, type, 4 more }` +## Delete a model response - A description of the chain of thought used by a reasoning model while generating - a response. Be sure to include these items in your `input` to the Responses API - for subsequent turns of a conversation if you are manually - [managing context](/docs/guides/conversation-state). +**delete** `/responses/{response_id}?beta=true` - - `id: string` +Deletes a model response with the given ID. - The unique identifier of the reasoning content. +### Header Parameters - - `summary: array of object { text, type }` +- `"openai-beta": optional array of "responses_multi_agent=v1"` - Reasoning summary content. + - `"responses_multi_agent=v1"` - - `text: string` +### Path Parameters - A summary of the reasoning output from the model so far. +- `response_id: string` - - `type: "summary_text"` +### Example - The type of the object. Always `summary_text`. +```http +curl https://api.openai.com/v1/responses/$RESPONSE_ID \ + -X DELETE \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `"summary_text"` +### Example - - `type: "reasoning"` +```http +curl -X DELETE https://api.openai.com/v1/responses/resp_123 \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - The type of the object. Always `reasoning`. +#### Response - - `"reasoning"` +```json +{ + "id": "resp_6786a1bec27481909a17d673315b29f6", + "object": "response", + "deleted": true +} +``` - - `agent: optional object { agent_name }` +## Get a model response - The agent that produced this item. +**get** `/responses/{response_id}?beta=true` - - `agent_name: string` +Retrieves a model response with the given ID. - The canonical name of the agent that produced this item. +### Header Parameters - - `content: optional array of object { text, type }` +- `"openai-beta": optional array of "responses_multi_agent=v1"` - Reasoning text content. + - `"responses_multi_agent=v1"` - - `text: string` +### Path Parameters - The reasoning text from the model. +- `response_id: string` - - `type: "reasoning_text"` +### Query Parameters - The type of the reasoning text. Always `reasoning_text`. +- `include: optional array of BetaResponseIncludable` - - `"reasoning_text"` + Additional fields to include in the response. See the `include` + parameter for Response creation above for more information. - - `encrypted_content: optional string` + - `"file_search_call.results"` - 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. + - `"web_search_call.results"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"web_search_call.action.sources"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"message.input_image.image_url"` - - `"in_progress"` + - `"computer_call_output.output.image_url"` - - `"completed"` + - `"code_interpreter_call.outputs"` - - `"incomplete"` + - `"reasoning.encrypted_content"` - - `Compaction object { id, encrypted_content, type, 2 more }` + - `"message.output_text.logprobs"` - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). +- `include_obfuscation: optional boolean` - - `id: string` + 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. - The unique ID of the compaction item. +- `starting_after: optional number` - - `encrypted_content: string` + The sequence number of the event after which to start streaming. - The encrypted content that was produced by compaction. +- `stream: optional false` - - `type: "compaction"` + 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. - The type of the item. Always `compaction`. + - `false` - - `"compaction"` +### Returns - - `agent: optional object { agent_name }` +- `BetaResponse object { id, created_at, error, 32 more }` - The agent that produced this item. + - `id: string` - - `agent_name: string` + Unique identifier for this Response. - The canonical name of the agent that produced this item. + - `created_at: number` - - `created_by: optional string` + Unix timestamp (in seconds) of when this Response was created. - The identifier of the actor that created the item. + - `error: BetaResponseError` - - `CodeInterpreterCall object { id, code, container_id, 4 more }` + An error object returned when the model fails to generate a Response. - A tool call to run code. + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 17 more` - - `id: string` + The error code for the response. - The unique ID of the code interpreter tool call. + - `"server_error"` - - `code: string` + - `"rate_limit_exceeded"` - The code to run, or null if not available. + - `"invalid_prompt"` - - `container_id: string` + - `"data_residency_mismatch"` - The ID of the container used to run the code. + - `"bio_policy"` - - `outputs: array of object { logs, type } or object { type, url }` + - `"vector_store_timeout"` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `"invalid_image"` - - `Logs object { logs, type }` + - `"invalid_image_format"` - The logs output from the code interpreter. + - `"invalid_base64_image"` - - `logs: string` + - `"invalid_image_url"` - The logs output from the code interpreter. + - `"image_too_large"` - - `type: "logs"` + - `"image_too_small"` - The type of the output. Always `logs`. + - `"image_parse_error"` - - `"logs"` + - `"image_content_policy_violation"` - - `Image object { type, url }` + - `"invalid_image_mode"` - The image output from the code interpreter. + - `"image_file_too_large"` - - `type: "image"` + - `"unsupported_image_media_type"` - The type of the output. Always `image`. + - `"empty_image_file"` - - `"image"` + - `"failed_to_download_image"` - - `url: string` + - `"image_file_not_found"` - The URL of the image output from the code interpreter. + - `message: string` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + A human-readable description of the error. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `incomplete_details: object { reason }` - - `"in_progress"` + Details about why the response is incomplete. - - `"completed"` + - `reason: optional "max_output_tokens" or "content_filter"` - - `"incomplete"` + The reason why the response is incomplete. - - `"interpreting"` + - `"max_output_tokens"` - - `"failed"` + - `"content_filter"` - - `type: "code_interpreter_call"` + - `instructions: string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - The type of the code interpreter tool call. Always `code_interpreter_call`. + A system (or developer) message inserted into the model's context. - - `"code_interpreter_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. - - `agent: optional object { agent_name }` + - `string` - The agent that produced this item. + A text input to the model, equivalent to a text input with the + `developer` role. - - `agent_name: string` + - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - The canonical name of the agent that produced this item. + A list of one or many input items to the model, containing + different content types. - - `LocalShellCall object { id, action, call_id, 3 more }` + - `BetaEasyInputMessage object { content, role, phase, type }` - A tool call to run a command on the 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. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. - - `id: string` + - `content: string or BetaResponseInputMessageContentList` - The unique ID of the local shell call. + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `action: object { command, env, type, 3 more }` + - `TextInput = string` - Execute a shell command on the server. + A text input to the model. - - `command: array of string` + - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` - The command to run. + A list of one or many input items to the model, containing different content + types. - - `env: map[string]` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - Environment variables to set for the command. + A text input to the model. - - `type: "exec"` + - `text: string` - The type of the local shell action. Always `exec`. + The text input to the model. - - `"exec"` + - `type: "input_text"` - - `timeout_ms: optional number` + The type of the input item. Always `input_text`. - Optional timeout in milliseconds for the command. + - `"input_text"` - - `user: optional string` + - `prompt_cache_breakpoint: optional object { mode }` - Optional user to run the command as. + 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. - - `working_directory: optional string` + - `mode: "explicit"` - Optional working directory to run the command in. + The breakpoint mode. Always `explicit`. - - `call_id: string` + - `"explicit"` - The unique ID of the local shell tool call generated by the model. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `status: "in_progress" or "completed" or "incomplete"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - The status of the local shell call. + - `detail: "low" or "high" or "auto" or "original"` - - `"in_progress"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"completed"` + - `"low"` - - `"incomplete"` + - `"high"` - - `type: "local_shell_call"` + - `"auto"` - The type of the local shell call. Always `local_shell_call`. + - `"original"` - - `"local_shell_call"` + - `type: "input_image"` - - `agent: optional object { agent_name }` + The type of the input item. Always `input_image`. - The agent that produced this item. + - `"input_image"` - - `agent_name: string` + - `file_id: optional string` - The canonical name of the agent that produced this item. + The ID of the file to be sent to the model. - - `LocalShellCallOutput object { id, output, type, 2 more }` + - `image_url: optional string` - The output of a local shell tool call. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `id: string` + - `prompt_cache_breakpoint: optional object { mode }` - The unique ID of the local shell tool call generated by the model. + 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. - - `output: string` + - `mode: "explicit"` - A JSON string of the output of the local shell tool call. + The breakpoint mode. Always `explicit`. - - `type: "local_shell_call_output"` + - `"explicit"` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `"local_shell_call_output"` + A file input to the model. - - `agent: optional object { agent_name }` + - `type: "input_file"` - The agent that produced this item. + The type of the input item. Always `input_file`. - - `agent_name: string` + - `"input_file"` - The canonical name of the agent that produced this item. + - `detail: optional "auto" or "low" or "high"` - - `status: optional "in_progress" or "completed" or "incomplete"` + 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 status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `"auto"` - - `"in_progress"` + - `"low"` - - `"completed"` + - `"high"` - - `"incomplete"` + - `file_data: optional string` - - `ShellCall object { id, action, call_id, 6 more }` + The content of the file to be sent to the model. - A tool call that executes one or more shell commands in a managed environment. + - `file_id: optional string` - - `id: string` + The ID of the file to be sent to the model. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `file_url: optional string` - - `action: object { commands, max_output_length, timeout_ms }` + The URL of the file to be sent to the model. - The shell commands and limits that describe how to run the tool call. + - `filename: optional string` - - `commands: array of string` + The name of the file to be sent to the model. - - `max_output_length: number` + - `prompt_cache_breakpoint: optional object { mode }` - Optional maximum number of characters to return from each command. + 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. - - `timeout_ms: number` + - `mode: "explicit"` - Optional timeout in milliseconds for the commands. + The breakpoint mode. Always `explicit`. - - `call_id: string` + - `"explicit"` - The unique ID of the shell tool call generated by the model. + - `role: "user" or "assistant" or "system" or "developer"` - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - Represents the use of a local environment to perform shell actions. + - `"user"` - - `BetaResponseLocalEnvironment object { type }` + - `"assistant"` - Represents the use of a local environment to perform shell actions. + - `"system"` - - `type: "local"` + - `"developer"` - The environment type. Always `local`. + - `phase: optional "commentary" or "final_answer"` - - `"local"` + 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. - - `BetaResponseContainerReference object { container_id, type }` + - `"commentary"` - Represents a container created with /v1/containers. + - `"final_answer"` - - `container_id: string` + - `type: optional "message"` - - `type: "container_reference"` + The type of the message input. Always `message`. - The environment type. Always `container_reference`. + - `"message"` - - `"container_reference"` + - `Message object { content, role, agent, 2 more }` - - `status: "in_progress" or "completed" or "incomplete"` + 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. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `content: BetaResponseInputMessageContentList` - - `"in_progress"` + A list of one or many input items to the model, containing different content + types. - - `"completed"` + - `role: "user" or "system" or "developer"` - - `"incomplete"` + The role of the message input. One of `user`, `system`, or `developer`. - - `type: "shell_call"` + - `"user"` - The type of the item. Always `shell_call`. + - `"system"` - - `"shell_call"` + - `"developer"` - `agent: optional object { agent_name }` @@ -49668,217 +48043,201 @@ Learn when and how to compact long-running conversations in the [conversation st The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. - - - `Direct object { type }` - - - `type: "direct"` - - - `"direct"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `Program object { caller_id, type }` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `caller_id: string` + - `"in_progress"` - The call ID of the program item that produced this tool call. + - `"completed"` - - `type: "program"` + - `"incomplete"` - - `"program"` + - `type: optional "message"` - - `created_by: optional string` + The type of the message input. Always set to `message`. - The ID of the entity that created this tool call. + - `"message"` - - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - The output of a shell tool call that was emitted. + An output message from the model. - `id: string` - The unique ID of the shell call output. Populated when this item is returned via API. - - - `call_id: string` - - The unique ID of the shell tool call generated by the model. - - - `max_output_length: number` - - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - - `output: array of object { outcome, stderr, stdout, created_by }` - - An array of shell call output contents + The unique ID of the output message. - - `outcome: object { type } or object { exit_code, type }` + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + The content of the output message. - - `Timeout object { type }` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - Indicates that the shell call exceeded its configured time limit. + A text output from the model. - - `type: "timeout"` + - `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 outcome type. Always `timeout`. + The annotations of the text output. - - `"timeout"` + - `FileCitation object { file_id, filename, index, type }` - - `Exit object { exit_code, type }` + A citation to a file. - Indicates that the shell commands finished and returned an exit code. + - `file_id: string` - - `exit_code: number` + The ID of the file. - Exit code from the shell process. + - `filename: string` - - `type: "exit"` + The filename of the file cited. - The outcome type. Always `exit`. + - `index: number` - - `"exit"` + The index of the file in the list of files. - - `stderr: string` + - `type: "file_citation"` - The standard error output that was captured. + The type of the file citation. Always `file_citation`. - - `stdout: string` + - `"file_citation"` - The standard output that was captured. + - `URLCitation object { end_index, start_index, title, 2 more }` - - `created_by: optional string` + A citation for a web resource used to generate a model response. - The identifier of the actor that created the item. + - `end_index: number` - - `status: "in_progress" or "completed" or "incomplete"` + The index of the last character of the URL citation in the message. - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `start_index: number` - - `"in_progress"` + The index of the first character of the URL citation in the message. - - `"completed"` + - `title: string` - - `"incomplete"` + The title of the web resource. - - `type: "shell_call_output"` + - `type: "url_citation"` - The type of the shell call output. Always `shell_call_output`. + The type of the URL citation. Always `url_citation`. - - `"shell_call_output"` + - `"url_citation"` - - `agent: optional object { agent_name }` + - `url: string` - The agent that produced this item. + The URL of the web resource. - - `agent_name: string` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - The canonical name of the agent that produced this item. + A citation for a container file used to generate a model response. - - `caller: optional object { type } or object { caller_id, type }` + - `container_id: string` - The execution context that produced this tool call. + The ID of the container file. - - `Direct object { type }` + - `end_index: number` - - `type: "direct"` + The index of the last character of the container file citation in the message. - - `"direct"` + - `file_id: string` - - `Program object { caller_id, type }` + The ID of the file. - - `caller_id: string` + - `filename: string` - The call ID of the program item that produced this tool call. + The filename of the container file cited. - - `type: "program"` + - `start_index: number` - - `"program"` + The index of the first character of the container file citation in the message. - - `created_by: optional string` + - `type: "container_file_citation"` - The identifier of the actor that created the item. + The type of the container file citation. Always `container_file_citation`. - - `ApplyPatchCall object { id, call_id, operation, 5 more }` + - `"container_file_citation"` - A tool call that applies file diffs by creating, deleting, or updating files. + - `FilePath object { file_id, index, type }` - - `id: string` + A path to a file. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `file_id: string` - - `call_id: string` + The ID of the file. - The unique ID of the apply patch tool call generated by the model. + - `index: number` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + The index of the file in the list of files. - One of the create_file, delete_file, or update_file operations applied via apply_patch. + - `type: "file_path"` - - `CreateFile object { diff, path, type }` + The type of the file path. Always `file_path`. - Instruction describing how to create a file via the apply_patch tool. + - `"file_path"` - - `diff: string` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - Diff to apply. + - `token: string` - - `path: string` + - `bytes: array of number` - Path of the file to create. + - `logprob: number` - - `type: "create_file"` + - `top_logprobs: array of object { token, bytes, logprob }` - Create a new file with the provided diff. + - `token: string` - - `"create_file"` + - `bytes: array of number` - - `DeleteFile object { path, type }` + - `logprob: number` - Instruction describing how to delete a file via the apply_patch tool. + - `text: string` - - `path: string` + The text output from the model. - Path of the file to delete. + - `type: "output_text"` - - `type: "delete_file"` + The type of the output text. Always `output_text`. - Delete the specified file. + - `"output_text"` - - `"delete_file"` + - `BetaResponseOutputRefusal object { refusal, type }` - - `UpdateFile object { diff, path, type }` + A refusal from the model. - Instruction describing how to update a file via the apply_patch tool. + - `refusal: string` - - `diff: string` + The refusal explanation from the model. - Diff to apply. + - `type: "refusal"` - - `path: string` + The type of the refusal. Always `refusal`. - Path of the file to update. + - `"refusal"` - - `type: "update_file"` + - `role: "assistant"` - Update an existing file with the provided diff. + The role of the output message. Always `assistant`. - - `"update_file"` + - `"assistant"` - - `status: "in_progress" or "completed"` + - `status: "in_progress" or "completed" or "incomplete"` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - `"in_progress"` - `"completed"` - - `type: "apply_patch_call"` + - `"incomplete"` - The type of the item. Always `apply_patch_call`. + - `type: "message"` - - `"apply_patch_call"` + The type of the output message. Always `message`. + + - `"message"` - `agent: optional object { agent_name }` @@ -49888,55 +48247,49 @@ Learn when and how to compact long-running conversations in the [conversation st The canonical name of the agent that produced this item. - - `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` + - `phase: optional "commentary" or "final_answer"` - The call ID of the program item 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. - - `type: "program"` + - `"commentary"` - - `"program"` + - `"final_answer"` - - `created_by: optional string` + - `FileSearchCall object { id, queries, status, 3 more }` - The ID of the entity that created this tool call. + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` + - `id: string` - The output emitted by an apply patch tool call. + The unique ID of the file search tool call. - - `id: string` + - `queries: array of string` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + The queries used to search for files. - - `call_id: string` + - `status: "in_progress" or "searching" or "completed" or 2 more` - The unique ID of the apply patch tool call generated by the model. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `status: "completed" or "failed"` + - `"in_progress"` - The status of the apply patch tool call output. One of `completed` or `failed`. + - `"searching"` - `"completed"` + - `"incomplete"` + - `"failed"` - - `type: "apply_patch_call_output"` + - `type: "file_search_call"` - The type of the item. Always `apply_patch_call_output`. + The type of the file search tool call. Always `file_search_call`. - - `"apply_patch_call_output"` + - `"file_search_call"` - `agent: optional object { agent_name }` @@ -49946,781 +48299,608 @@ Learn when and how to compact long-running conversations in the [conversation st The canonical name of the agent that produced this item. - - `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. - - - `McpListTools object { id, server_label, tools, 3 more }` - - A list of tools available on an MCP server. - - - `id: string` - - The unique ID of the list. - - - `server_label: string` - - The label of the MCP server. - - - `tools: array of object { input_schema, name, annotations, description }` - - The tools available on the server. - - - `input_schema: unknown` - - The JSON schema describing the tool's input. - - - `name: string` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - The name of the tool. + The results of the file search tool call. - - `annotations: optional unknown` + - `attributes: optional map[string or number or boolean]` - Additional annotations about the tool. + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - - `description: optional string` + - `string` - The description of the tool. + - `number` - - `type: "mcp_list_tools"` + - `boolean` - The type of the item. Always `mcp_list_tools`. + - `file_id: optional string` - - `"mcp_list_tools"` + The unique ID of the file. - - `agent: optional object { agent_name }` + - `filename: optional string` - The agent that produced this item. + The name of the file. - - `agent_name: string` + - `score: optional number` - The canonical name of the agent that produced this item. + The relevance score of the file - a value between 0 and 1. - - `error: optional string` + - `text: optional string` - Error message if the server could not list tools. + The text that was retrieved from the file. - - `McpApprovalRequest object { id, arguments, name, 3 more }` + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - A request for human approval of a tool invocation. + 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 approval request. - - - `arguments: string` - - A JSON string of arguments for the tool. - - - `name: string` - - The name of the tool to run. - - - `server_label: string` - - The label of the MCP server making the request. - - - `type: "mcp_approval_request"` - - The type of the item. Always `mcp_approval_request`. - - - `"mcp_approval_request"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. + The unique ID of the computer call. - - `agent_name: string` + - `call_id: string` - The canonical name of the agent that produced this item. + An identifier used when responding to the tool call with output. - - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` + - `pending_safety_checks: array of object { id, code, message }` - A response to an MCP approval request. + The pending safety checks for the computer call. - `id: string` - The unique ID of the approval response - - - `approval_request_id: string` - - The ID of the approval request being answered. - - - `approve: boolean` - - Whether the request was approved. - - - `type: "mcp_approval_response"` + The ID of the pending safety check. - The type of the item. Always `mcp_approval_response`. + - `code: optional string` - - `"mcp_approval_response"` + The type of the pending safety check. - - `agent: optional object { agent_name }` + - `message: optional string` - The agent that produced this item. + Details about the pending safety check. - - `agent_name: string` + - `status: "in_progress" or "completed" or "incomplete"` - The canonical name of the agent that produced this item. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `reason: optional string` + - `"in_progress"` - Optional reason for the decision. + - `"completed"` - - `McpCall object { id, arguments, name, 7 more }` + - `"incomplete"` - An invocation of a tool on an MCP server. + - `type: "computer_call"` - - `id: string` + The type of the computer call. Always `computer_call`. - The unique ID of the tool call. + - `"computer_call"` - - `arguments: string` + - `action: optional BetaComputerAction` - A JSON string of the arguments passed to the tool. + A click action. - - `name: string` + - `Click object { button, type, x, 2 more }` - The name of the tool that was run. + A click action. - - `server_label: string` + - `button: "left" or "right" or "wheel" or 2 more` - The label of the MCP server running the tool. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `type: "mcp_call"` + - `"left"` - The type of the item. Always `mcp_call`. + - `"right"` - - `"mcp_call"` + - `"wheel"` - - `agent: optional object { agent_name }` + - `"back"` - The agent that produced this item. + - `"forward"` - - `agent_name: string` + - `type: "click"` - The canonical name of the agent that produced this item. + Specifies the event type. For a click action, this property is always `click`. - - `approval_request_id: optional string` + - `"click"` - 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. + - `x: number` - - `error: optional string` + The x-coordinate where the click occurred. - The error from the tool call, if any. + - `y: number` - - `output: optional string` + The y-coordinate where the click occurred. - The output from the tool call. + - `keys: optional array of string` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + The keys being held while clicking. - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `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. - - `"calling"` + - `type: "double_click"` - - `"failed"` + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `CustomToolCall object { call_id, input, name, 5 more }` + - `"double_click"` - A call to a custom tool created by the model. + - `x: number` - - `call_id: string` + The x-coordinate where the double click occurred. - An identifier used to map this custom tool call to a tool call output. + - `y: number` - - `input: string` + The y-coordinate where the double click occurred. - The input for the custom tool call generated by the model. + - `Drag object { path, type, keys }` - - `name: string` + A drag action. - The name of the custom tool being called. + - `path: array of object { x, y }` - - `type: "custom_tool_call"` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The type of the custom tool call. Always `custom_tool_call`. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `"custom_tool_call"` + - `x: number` - - `id: optional string` + The x-coordinate. - The unique ID of the custom tool call in the OpenAI platform. + - `y: number` - - `agent: optional object { agent_name }` + The y-coordinate. - The agent that produced this item. + - `type: "drag"` - - `agent_name: string` + Specifies the event type. For a drag action, this property is always set to `drag`. - The canonical name of the agent that produced this item. + - `"drag"` - - `caller: optional object { type } or object { caller_id, type }` + - `keys: optional array of string` - The execution context that produced this tool call. + The keys being held while dragging the mouse. - - `Direct object { type }` + - `Keypress object { keys, type }` - - `type: "direct"` + A collection of keypresses the model would like to perform. - - `"direct"` + - `keys: array of string` - - `Program object { caller_id, type }` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `caller_id: string` + - `type: "keypress"` - The call ID of the program item that produced this tool call. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `type: "program"` + - `"keypress"` - - `"program"` + - `Move object { type, x, y, keys }` - - `namespace: optional string` + A mouse move action. - The namespace of the custom tool being called. + - `type: "move"` - - `CustomToolCallOutput object { call_id, output, type, 3 more }` + Specifies the event type. For a move action, this property is always set to `move`. - The output of a custom tool call from your code, being sent back to the model. + - `"move"` - - `call_id: string` + - `x: number` - The call ID, used to map this custom tool call output to a custom tool call. + The x-coordinate to move to. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `y: number` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + The y-coordinate to move to. - - `StringOutput = string` + - `keys: optional array of string` - A string of the output of the custom tool call. + The keys being held while moving the mouse. - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `Screenshot object { type }` - Text, image, or file output of the custom tool call. + A screenshot action. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `type: "screenshot"` - A text input to the model. + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `"screenshot"` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + A scroll action. - A file input to the model. + - `scroll_x: number` - - `type: "custom_tool_call_output"` + The horizontal scroll distance. - The type of the custom tool call output. Always `custom_tool_call_output`. + - `scroll_y: number` - - `"custom_tool_call_output"` + The vertical scroll distance. - - `id: optional string` + - `type: "scroll"` - The unique ID of the custom tool call output in the OpenAI platform. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `agent: optional object { agent_name }` + - `"scroll"` - The agent that produced this item. + - `x: number` - - `agent_name: string` + The x-coordinate where the scroll occurred. - The canonical name of the agent that produced this item. + - `y: number` - - `caller: optional object { type } or object { caller_id, type }` + The y-coordinate where the scroll occurred. - The execution context that produced this tool call. + - `keys: optional array of string` - - `Direct object { type }` + The keys being held while scrolling. - - `type: "direct"` + - `Type object { text, type }` - The caller type. Always `direct`. + An action to type in text. - - `"direct"` + - `text: string` - - `Program object { caller_id, type }` + The text to type. - - `caller_id: string` + - `type: "type"` - The call ID of the program item that produced this tool call. + Specifies the event type. For a type action, this property is always set to `type`. - - `type: "program"` + - `"type"` - The caller type. Always `program`. + - `Wait object { type }` - - `"program"` + A wait action. - - `usage: BetaResponseUsage` + - `type: "wait"` - Token accounting for the compaction pass, including cached, reasoning, and total tokens. + Specifies the event type. For a wait action, this property is always set to `wait`. - - `input_tokens: number` + - `"wait"` - The number of input tokens. + - `actions: optional BetaComputerActionList` - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - A detailed breakdown of the input tokens. + - `Click object { button, type, x, 2 more }` - - `cache_write_tokens: number` + A click action. - The number of input tokens that were written to the cache. + - `DoubleClick object { keys, type, x, y }` - - `cached_tokens: number` + A double click action. - The number of tokens that were retrieved from the cache. - [More on prompt caching](/docs/guides/prompt-caching). + - `Drag object { path, type, keys }` - - `output_tokens: number` + A drag action. - The number of output tokens. + - `Keypress object { keys, type }` - - `output_tokens_details: object { reasoning_tokens }` + A collection of keypresses the model would like to perform. - A detailed breakdown of the output tokens. + - `Move object { type, x, y, keys }` - - `reasoning_tokens: number` + A mouse move action. - The number of reasoning tokens. + - `Screenshot object { type }` - - `total_tokens: number` + A screenshot action. - The total number of tokens used. + - `Scroll object { scroll_x, scroll_y, type, 3 more }` -### Example + A scroll action. -```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" - }' -``` + - `Type object { text, type }` -#### Response + An action to type in text. -```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", - "agent": { - "agent_name": "agent_name" - }, - "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 - } -} -``` + - `Wait object { type }` -### Example + A wait action. -```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" - } - ] - }' -``` + - `agent: optional object { agent_name }` -#### Response + The agent that produced this item. -```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 - } -} -``` + - `agent_name: string` -## Domain Types + The canonical name of the agent that produced this item. -### Beta Compacted Response + - `ComputerCallOutput object { call_id, output, type, 4 more }` -- `BetaCompactedResponse object { id, created_at, object, 2 more }` + The output of a computer tool call. - - `id: string` + - `call_id: string` - The unique identifier for the compacted response. + The ID of the computer tool call that produced the output. - - `created_at: number` + - `output: BetaResponseComputerToolCallOutputScreenshot` - Unix timestamp (in seconds) when the compacted conversation was created. + A computer screenshot image used with the computer use tool. - - `object: "response.compaction"` + - `type: "computer_screenshot"` - The object type. Always `response.compaction`. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `"response.compaction"` + - `"computer_screenshot"` - - `output: array of object { id, content, role, 4 more } or object { id, call_id, code, 3 more } or object { id, call_id, result, 3 more } or 28 more` + - `file_id: optional string` - The compacted list of output items. + The identifier of an uploaded file that contains the screenshot. - - `Message object { id, content, role, 4 more }` + - `image_url: optional string` - A message to or from the model. + The URL of the screenshot image. - - `id: string` + - `type: "computer_call_output"` - The unique ID of the message. + The type of the computer tool call output. Always `computer_call_output`. - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + - `"computer_call_output"` - The content of the message + - `id: optional string` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + The ID of the computer tool call output. - A text input to the model. + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `text: string` + The safety checks reported by the API that have been acknowledged by the developer. - The text input to the model. + - `id: string` - - `type: "input_text"` + The ID of the pending safety check. - The type of the input item. Always `input_text`. + - `code: optional string` - - `"input_text"` + The type of the pending safety check. - - `prompt_cache_breakpoint: optional object { mode }` + - `message: 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. + Details about the pending safety check. - - `mode: "explicit"` + - `agent: optional object { agent_name }` - The breakpoint mode. Always `explicit`. + The agent that produced this item. - - `"explicit"` + - `agent_name: string` - - `BetaResponseOutputText object { annotations, logprobs, text, type }` + The canonical name of the agent that produced this item. - A text output from the model. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - The annotations of the text output. + - `"in_progress"` - - `FileCitation object { file_id, filename, index, type }` + - `"completed"` - A citation to a file. + - `"incomplete"` - - `file_id: string` + - `WebSearchCall object { id, action, status, 2 more }` - The ID of the file. + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `filename: string` + - `id: string` - The filename of the file cited. + The unique ID of the web search tool call. - - `index: number` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - The index of the file in the list of files. + 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). - - `type: "file_citation"` + - `Search object { type, queries, query, sources }` - The type of the file citation. Always `file_citation`. + Action type "search" - Performs a web search query. - - `"file_citation"` + - `type: "search"` - - `URLCitation object { end_index, start_index, title, 2 more }` + The action type. - A citation for a web resource used to generate a model response. + - `"search"` - - `end_index: number` + - `queries: optional array of string` - The index of the last character of the URL citation in the message. + The search queries. - - `start_index: number` + - `query: optional string` - The index of the first character of the URL citation in the message. + The search query. - - `title: string` + - `sources: optional array of object { type, url }` - The title of the web resource. + The sources used in the search. - - `type: "url_citation"` + - `type: "url"` - The type of the URL citation. Always `url_citation`. + The type of source. Always `url`. - - `"url_citation"` + - `"url"` - `url: string` - The URL of the web resource. + The URL of the source. - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + - `OpenPage object { type, url }` - A citation for a container file used to generate a model response. + Action type "open_page" - Opens a specific URL from search results. - - `container_id: string` + - `type: "open_page"` - The ID of the container file. + The action type. - - `end_index: number` + - `"open_page"` - The index of the last character of the container file citation in the message. + - `url: optional string` - - `file_id: string` + The URL opened by the model. - The ID of the file. + - `FindInPage object { pattern, type, url }` - - `filename: string` + Action type "find_in_page": Searches for a pattern within a loaded page. - The filename of the container file cited. + - `pattern: string` - - `start_index: number` + The pattern or text to search for within the page. - The index of the first character of the container file citation in the message. + - `type: "find_in_page"` - - `type: "container_file_citation"` + The action type. - The type of the container file citation. Always `container_file_citation`. + - `"find_in_page"` - - `"container_file_citation"` + - `url: string` - - `FilePath object { file_id, index, type }` + The URL of the page searched for the pattern. - A path to a file. + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `file_id: string` + The status of the web search tool call. - The ID of the file. + - `"in_progress"` - - `index: number` + - `"searching"` - The index of the file in the list of files. + - `"completed"` - - `type: "file_path"` + - `"failed"` - The type of the file path. Always `file_path`. + - `type: "web_search_call"` - - `"file_path"` + The type of the web search tool call. Always `web_search_call`. - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `"web_search_call"` - - `token: string` + - `agent: optional object { agent_name }` - - `bytes: array of number` + The agent that produced this item. - - `logprob: number` + - `agent_name: string` - - `top_logprobs: array of object { token, bytes, logprob }` + The canonical name of the agent that produced this item. - - `token: string` + - `FunctionCall object { arguments, call_id, name, 6 more }` - - `bytes: array of number` + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `logprob: number` + - `arguments: string` - - `text: string` + A JSON string of the arguments to pass to the function. - The text output from the model. + - `call_id: string` - - `type: "output_text"` + The unique ID of the function tool call generated by the model. - The type of the output text. Always `output_text`. + - `name: string` - - `"output_text"` + The name of the function to run. - - `Text object { text, type }` + - `type: "function_call"` - A text content. + The type of the function tool call. Always `function_call`. - - `text: string` + - `"function_call"` - - `type: "text"` + - `id: optional string` - - `"text"` + The unique ID of the function tool call. - - `SummaryText object { text, type }` + - `agent: optional object { agent_name }` - A summary text from the model. + The agent that produced this item. - - `text: string` + - `agent_name: string` - A summary of the reasoning output from the model so far. + The canonical name of the agent that produced this item. - - `type: "summary_text"` + - `caller: optional object { type } or object { caller_id, type }` - The type of the object. Always `summary_text`. + The execution context that produced this tool call. - - `"summary_text"` + - `Direct object { type }` - - `ReasoningText object { text, type }` + - `type: "direct"` - Reasoning text from the model. + - `"direct"` - - `text: string` + - `Program object { caller_id, type }` - The reasoning text from the model. + - `caller_id: string` - - `type: "reasoning_text"` + The call ID of the program item that produced this tool call. - The type of the reasoning text. Always `reasoning_text`. + - `type: "program"` - - `"reasoning_text"` + - `"program"` - - `BetaResponseOutputRefusal object { refusal, type }` + - `namespace: optional string` - A refusal from the model. + The namespace of the function to run. - - `refusal: string` + - `status: optional "in_progress" or "completed" or "incomplete"` - The refusal explanation from the model. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `type: "refusal"` + - `"in_progress"` - The type of the refusal. Always `refusal`. + - `"completed"` - - `"refusal"` + - `"incomplete"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `FunctionCallOutput object { call_id, output, type, 4 more }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + The output of a function tool call. - - `detail: "low" or "high" or "auto" or "original"` + - `call_id: string` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The unique ID of the function tool call generated by the model. - - `"low"` + - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - - `"high"` + Text, image, or file output of the function tool call. - - `"auto"` + - `string` - - `"original"` + A JSON string of the output of the function tool call. - - `type: "input_image"` + - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - The type of the input item. Always `input_image`. + An array of content outputs (text, image, file) for the function tool call. - - `"input_image"` + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - - `file_id: optional string` + A text input to the model. - The ID of the file to be sent to the model. + - `text: string` - - `image_url: optional string` + The text 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. + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `"input_text"` - `prompt_cache_breakpoint: optional object { mode }` @@ -50732,13 +48912,19 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"explicit"` - - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - A screenshot of a computer. + 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 detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The type of the input item. Always `input_image`. + + - `"input_image"` + + - `detail: optional "low" or "high" or "auto" or "original"` + + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - `"low"` @@ -50748,19 +48934,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"original"` - - `file_id: string` - - The identifier of an uploaded file that contains the screenshot. - - - `image_url: string` - - The URL of the screenshot image. + - `file_id: optional string` - - `type: "computer_screenshot"` + The ID of the file to be sent to the model. - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `image_url: optional string` - - `"computer_screenshot"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - `prompt_cache_breakpoint: optional object { mode }` @@ -50772,7 +48952,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"explicit"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` A file input to the model. @@ -50794,7 +48974,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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` @@ -50818,55 +48998,15 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"explicit"` - - `EncryptedContent object { encrypted_content, type }` - - Opaque encrypted content that Responses API decrypts inside trusted model execution. - - - `encrypted_content: string` - - Opaque encrypted content. - - - `type: "encrypted_content"` - - The type of the input item. Always `encrypted_content`. - - - `"encrypted_content"` - - - `role: "unknown" or "user" or "assistant" or 5 more` - - The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. - - - `"unknown"` - - - `"user"` - - - `"assistant"` - - - `"system"` - - - `"critic"` - - - `"discriminator"` - - - `"developer"` - - - `"tool"` - - - `status: "in_progress" or "completed" or "incomplete"` - - The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` + - `type: "function_call_output"` - - `"incomplete"` + The type of the function tool call output. Always `function_call_output`. - - `type: "message"` + - `"function_call_output"` - The type of the message. Always set to `message`. + - `id: optional string` - - `"message"` + The unique ID of the function tool call output. Populated when this item is returned via API. - `agent: optional object { agent_name }` @@ -50876,108 +49016,87 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `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"` - - - `Program object { id, call_id, code, 3 more }` + - `caller: optional object { type } or object { caller_id, type }` - - `id: string` + The execution context that produced this tool call. - The unique ID of the program item. + - `Direct object { type }` - - `call_id: string` + - `type: "direct"` - The stable call ID of the program item. + The caller type. Always `direct`. - - `code: string` + - `"direct"` - The JavaScript source executed by programmatic tool calling. + - `Program object { caller_id, type }` - - `fingerprint: string` + - `caller_id: string` - Opaque program replay fingerprint that must be round-tripped. + The call ID of the program item that produced this tool call. - `type: "program"` - The type of the item. Always `program`. + The caller type. Always `program`. - `"program"` - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `ProgramOutput object { id, call_id, result, 3 more }` - - - `id: string` - - The unique ID of the program output item. + - `status: optional "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 call ID of the program item. + - `"in_progress"` - - `result: string` + - `"completed"` - The result produced by the program item. + - `"incomplete"` - - `status: "completed" or "incomplete"` + - `AgentMessage object { author, content, recipient, 3 more }` - The terminal status of the program output item. + A message routed between agents. - - `"completed"` + - `author: string` - - `"incomplete"` + The sending agent identity. - - `type: "program_output"` + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - The type of the item. Always `program_output`. + Plaintext, image, or encrypted content sent between agents. - - `"program_output"` + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - - `agent: optional object { agent_name }` + A text input to the model. - The agent that produced this item. + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - - `agent_name: string` + An image input to the model. Learn about [image inputs](/docs/guides/vision) - The canonical name of the agent that produced this item. + - `EncryptedContent object { encrypted_content, type }` - - `FunctionCall object { arguments, call_id, name, 6 more }` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - A tool call to run a function. See the - [function calling guide](/docs/guides/function-calling) for more information. + - `encrypted_content: string` - - `arguments: string` + Opaque encrypted content. - A JSON string of the arguments to pass to the function. + - `type: "encrypted_content"` - - `call_id: string` + The type of the input item. Always `encrypted_content`. - The unique ID of the function tool call generated by the model. + - `"encrypted_content"` - - `name: string` + - `recipient: string` - The name of the function to run. + The destination agent identity. - - `type: "function_call"` + - `type: "agent_message"` - The type of the function tool call. Always `function_call`. + The item type. Always `agent_message`. - - `"function_call"` + - `"agent_message"` - `id: optional string` - The unique ID of the function tool call. + The unique ID of this agent message item. - `agent: optional object { agent_name }` @@ -50987,50 +49106,11 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. - - - `Direct object { type }` - - - `type: "direct"` - - - `"direct"` - - - `Program object { caller_id, type }` - - - `caller_id: string` - - The call ID of the program item that produced this tool call. - - - `type: "program"` - - - `"program"` - - - `namespace: optional string` - - The namespace of the function to run. - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `MultiAgentCall object { id, action, arguments, 3 more }` - - - `id: string` - - The unique ID of the multi-agent call item. + - `MultiAgentCall object { action, arguments, call_id, 3 more }` - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - The multi-agent action to execute. + The multi-agent action that was executed. - `"spawn_agent"` @@ -51046,7 +49126,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `arguments: string` - The JSON string of arguments generated for the action. + The action arguments as a JSON string. - `call_id: string` @@ -51054,10 +49134,14 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "multi_agent_call"` - The type of the multi-agent call. Always `multi_agent_call`. + The item type. Always `multi_agent_call`. - `"multi_agent_call"` + - `id: optional string` + + The unique ID of this multi-agent call. + - `agent: optional object { agent_name }` The agent that produced this item. @@ -51066,11 +49150,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `MultiAgentCallOutput object { id, action, call_id, 3 more }` - - - `id: string` - - The unique ID of the multi-agent call output item. + - `MultiAgentCallOutput object { action, call_id, output, 3 more }` - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` @@ -51092,75 +49172,105 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The unique ID of the multi-agent call. - - `output: array of BetaResponseOutputText` + - `output: array of object { text, type, annotations }` Text output returned by the multi-agent action. - - `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 }` + - `text: string` - The annotations of the text output. + The text content. - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `type: "output_text"` - - `text: string` + The content type. Always `output_text`. - The text output from the model. + - `"output_text"` - - `type: "output_text"` + - `annotations: optional 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 }` - The type of the output text. Always `output_text`. + Citations associated with the text content. - - `type: "multi_agent_call_output"` + - `FileCitation object { file_id, filename, index, type }` - The type of the multi-agent result. Always `multi_agent_call_output`. + - `file_id: string` - - `"multi_agent_call_output"` + The ID of the file. - - `agent: optional object { agent_name }` + - `filename: string` - The agent that produced this item. + The filename of the file cited. - - `agent_name: string` + - `index: number` - The canonical name of the agent that produced this item. + The index of the file in the list of files. - - `ToolSearchCall object { id, arguments, call_id, 5 more }` + - `type: "file_citation"` - - `id: string` + The citation type. Always `file_citation`. - The unique ID of the tool search call item. + - `"file_citation"` - - `arguments: unknown` + - `URLCitation object { end_index, start_index, title, 2 more }` - Arguments used for the tool search call. + - `end_index: number` - - `call_id: string` + The index of the last character of the citation in the message. - The unique ID of the tool search call generated by the model. + - `start_index: number` - - `execution: "server" or "client"` + The index of the first character of the citation in the message. - Whether tool search was executed by the server or by the client. + - `title: string` - - `"server"` + The title of the cited resource. - - `"client"` + - `type: "url_citation"` - - `status: "in_progress" or "completed" or "incomplete"` + The citation type. Always `url_citation`. - The status of the tool search call item that was recorded. + - `"url_citation"` - - `"in_progress"` + - `url: string` - - `"completed"` + The URL of the cited resource. - - `"incomplete"` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - - `type: "tool_search_call"` + - `container_id: string` - The type of the item. Always `tool_search_call`. + The ID of the container. - - `"tool_search_call"` + - `end_index: number` + + The index of the last character of the citation in the message. + + - `file_id: string` + + The ID of the container file. + + - `filename: string` + + The filename of the container file cited. + + - `start_index: number` + + The index of the first character of the citation in the message. + + - `type: "container_file_citation"` + + The citation type. Always `container_file_citation`. + + - `"container_file_citation"` + + - `type: "multi_agent_call_output"` + + The item type. Always `multi_agent_call_output`. + + - `"multi_agent_call_output"` + + - `id: optional string` + + The unique ID of this multi-agent call output. - `agent: optional object { agent_name }` @@ -51170,21 +49280,35 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` + - `ToolSearchCall object { arguments, type, id, 4 more }` - The identifier of the actor that created the item. + - `arguments: unknown` - - `ToolSearchOutput object { id, call_id, execution, 5 more }` + The arguments supplied to the tool search call. - - `id: string` + - `type: "tool_search_call"` - The unique ID of the tool search output item. + The item type. Always `tool_search_call`. - - `call_id: string` + - `"tool_search_call"` + + - `id: optional string` + + The unique ID of this tool search call. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `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. @@ -51192,9 +49316,9 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"client"` - - `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 tool search call. - `"in_progress"` @@ -51202,9 +49326,11 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` + - `ToolSearchOutput object { tools, type, id, 4 more }` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - The loaded tool definitions returned by tool search. + The loaded tool definitions returned by the tool search output. - `Function object { name, parameters, strict, 5 more }` @@ -52347,10 +50473,14 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "tool_search_output"` - The type of the item. Always `tool_search_output`. + The item type. Always `tool_search_output`. - `"tool_search_output"` + - `id: optional string` + + The unique ID of this tool search output. + - `agent: optional object { agent_name }` The agent that produced this item. @@ -52359,39 +50489,39 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` + - `call_id: optional string` - The identifier of the actor that created the item. + The unique ID of the tool search call generated by the model. - - `AdditionalTools object { id, role, tools, 2 more }` + - `execution: optional "server" or "client"` - - `id: string` + Whether tool search was executed by the server or by the client. - The unique ID of the additional tools item. + - `"server"` - - `role: "unknown" or "user" or "assistant" or 5 more` + - `"client"` - The role that provided the additional tools. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"unknown"` + The status of the tool search output. - - `"user"` + - `"in_progress"` - - `"assistant"` + - `"completed"` - - `"system"` + - `"incomplete"` - - `"critic"` + - `AdditionalTools object { role, tools, type, 2 more }` - - `"discriminator"` + - `role: "developer"` - - `"developer"` + The role that provided the additional tools. Only `developer` is supported. - - `"tool"` + - `"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 }` @@ -53158,1047 +51288,239 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"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 object { type } or object { definition, syntax, type }` - - 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"` - - - `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: "additional_tools"` - - The type of the item. Always `additional_tools`. - - - `"additional_tools"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `AgentMessage object { id, author, content, 3 more }` - - - `id: string` - - The unique ID of the agent message. - - - `author: string` - - The sending agent identity. - - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - - Encrypted content sent between agents. - - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `BetaResponseOutputText object { annotations, logprobs, text, type }` - - A text output from the model. - - - `Text object { text, type }` - - A text content. - - - `text: string` - - - `type: "text"` - - - `"text"` - - - `SummaryText object { text, type }` - - A summary text from the model. - - - `text: string` - - A summary of the reasoning output from the model so far. - - - `type: "summary_text"` - - The type of the object. Always `summary_text`. - - - `"summary_text"` - - - `ReasoningText object { text, type }` - - Reasoning text from the model. - - - `text: string` - - The reasoning text from the model. - - - `type: "reasoning_text"` - - The type of the reasoning text. Always `reasoning_text`. - - - `"reasoning_text"` - - - `BetaResponseOutputRefusal object { refusal, type }` - - A refusal from the model. - - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](/docs/guides/vision). - - - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` - - A screenshot of a computer. - - - `detail: "low" or "high" or "auto" or "original"` - - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `"low"` - - - `"high"` - - - `"auto"` - - - `"original"` - - - `file_id: string` - - The identifier of an uploaded file that contains the screenshot. - - - `image_url: string` - - The URL of the screenshot image. - - - `type: "computer_screenshot"` - - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - - `"computer_screenshot"` - - - `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"` - - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - A file input to the model. - - - `EncryptedContent object { encrypted_content, type }` - - Opaque encrypted content that Responses API decrypts inside trusted model execution. - - - `encrypted_content: string` - - Opaque encrypted content. - - - `type: "encrypted_content"` - - The type of the input item. Always `encrypted_content`. - - - `"encrypted_content"` - - - `recipient: string` - - The destination agent identity. - - - `type: "agent_message"` - - The type of the item. Always `agent_message`. - - - `"agent_message"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `FunctionCallOutput object { call_id, output, type, 4 more }` - - The output of a function tool call. - - - `call_id: string` - - The unique ID of the function tool call generated by the model. - - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - The output from the function call generated by your code. - Can be a string or an list of output content. - - - `StringOutput = string` - - A string of the output of the function call. - - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - Text, image, or file output of the function call. - - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](/docs/guides/vision). - - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - A file input to the model. - - - `type: "function_call_output"` - - The type of the function tool call output. Always `function_call_output`. - - - `"function_call_output"` - - - `id: optional string` - - The unique ID of the function tool call output. Populated when this item - is returned via API. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `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"` - - - `FileSearchCall object { id, queries, status, 3 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"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `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. - - - `WebSearchCall object { id, action, status, 2 more }` - - The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. - - - `id: string` - - The unique ID of the web search tool call. - - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). - - - `Search object { type, queries, query, sources }` - - Action type "search" - Performs a web search query. - - - `type: "search"` - - The action type. - - - `"search"` - - - `queries: optional array of string` - - The search queries. - - - `query: optional string` - - The search query. - - - `sources: optional array of object { type, url }` - - The sources used in the search. - - - `type: "url"` - - The type of source. Always `url`. - - - `"url"` - - - `url: string` - - The URL of the source. - - - `OpenPage object { type, url }` - - Action type "open_page" - Opens a specific URL from search results. - - - `type: "open_page"` - - The action type. - - - `"open_page"` - - - `url: optional string` - - The URL opened by the model. - - - `FindInPage object { pattern, type, url }` - - Action type "find_in_page": Searches for a pattern within a loaded page. - - - `pattern: string` - - The pattern or text to search for within the page. - - - `type: "find_in_page"` - - The action type. - - - `"find_in_page"` - - - `url: string` - - The URL of the page searched for the pattern. - - - `status: "in_progress" or "searching" or "completed" or "failed"` - - The status of the web search tool call. - - - `"in_progress"` - - - `"searching"` - - - `"completed"` - - - `"failed"` - - - `type: "web_search_call"` - - The type of the web search tool call. Always `web_search_call`. - - - `"web_search_call"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `ImageGenerationCall object { id, result, status, 2 more }` - - An image generation request made by the model. - - - `id: string` - - The unique ID of the image generation call. - - - `result: string` - - The generated image encoded in base64. - - - `status: "in_progress" or "completed" or "generating" or "failed"` - - The status of the image generation call. - - - `"in_progress"` - - - `"completed"` - - - `"generating"` - - - `"failed"` - - - `type: "image_generation_call"` - - The type of the image generation call. Always `image_generation_call`. - - - `"image_generation_call"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `ComputerCall object { id, call_id, pending_safety_checks, 5 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 BetaComputerAction` - - 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 }` + - `type: "grammar"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + Grammar format. Always `grammar`. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `"grammar"` - - `x: number` + - `Namespace object { description, name, tools, type }` - The x-coordinate. + Groups function/custom tools under a shared namespace. - - `y: number` + - `description: string` - The y-coordinate. + A description of the namespace shown to the model. - - `type: "drag"` + - `name: string` - Specifies the event type. For a drag action, this property is always set to `drag`. + The namespace name used in tool calls (for example, `crm`). - - `"drag"` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `keys: optional array of string` + The function/custom tools available inside this namespace. - The keys being held while dragging the mouse. + - `Function object { name, type, allowed_callers, 5 more }` - - `Keypress object { keys, type }` + - `name: string` - A collection of keypresses the model would like to perform. + - `type: "function"` - - `keys: array of string` + - `"function"` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "keypress"` + The tool invocation context(s). - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `"direct"` - - `"keypress"` + - `"programmatic"` - - `Move object { type, x, y, keys }` + - `defer_loading: optional boolean` - A mouse move action. + Whether this function should be deferred and discovered via tool search. - - `type: "move"` + - `description: optional string` - Specifies the event type. For a move action, this property is always set to `move`. + - `output_schema: optional map[unknown]` - - `"move"` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `x: number` + - `parameters: optional unknown` - The x-coordinate to move to. + - `strict: optional boolean` - - `y: number` + 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 y-coordinate to move to. + - `Custom object { name, type, allowed_callers, 3 more }` - - `keys: optional array of string` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - The keys being held while moving the mouse. + - `name: string` - - `Screenshot object { type }` + The name of the custom tool, used to identify it in tool calls. - A screenshot action. + - `type: "custom"` - - `type: "screenshot"` + The type of the custom tool. Always `custom`. - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `"custom"` - - `"screenshot"` + - `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"` - - `scroll_x: number` + - `"programmatic"` - The horizontal scroll distance. + - `defer_loading: optional boolean` - - `scroll_y: number` + Whether this tool should be deferred and discovered via tool search. - The vertical scroll distance. + - `description: optional string` - - `type: "scroll"` + Optional description of the custom tool, used to provide more context. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `format: optional object { type } or object { definition, syntax, type }` - - `"scroll"` + The input format for the custom tool. Default is unconstrained text. - - `x: number` + - `Text object { type }` - The x-coordinate where the scroll occurred. + Unconstrained free-form text. - - `y: number` + - `type: "text"` - The y-coordinate where the scroll occurred. + Unconstrained text format. Always `text`. - - `keys: optional array of string` + - `"text"` - The keys being held while scrolling. + - `Grammar object { definition, syntax, type }` - - `Type object { text, type }` + A grammar defined by the user. - An action to type in text. + - `definition: string` - - `text: string` + The grammar definition. - The text to type. + - `syntax: "lark" or "regex"` - - `type: "type"` + The syntax of the grammar definition. One of `lark` or `regex`. - Specifies the event type. For a type action, this property is always set to `type`. + - `"lark"` - - `"type"` + - `"regex"` - - `Wait object { type }` + - `type: "grammar"` - A wait action. + Grammar format. Always `grammar`. - - `type: "wait"` + - `"grammar"` - Specifies the event type. For a wait action, this property is always set to `wait`. + - `type: "namespace"` - - `"wait"` + The type of the tool. Always `namespace`. - - `actions: optional BetaComputerActionList` + - `"namespace"` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `ToolSearch object { type, description, execution, parameters }` - - `Click object { button, type, x, 2 more }` + Hosted or BYOT tool search configuration for deferred tools. - A click action. + - `type: "tool_search"` - - `DoubleClick object { keys, type, x, y }` + The type of the tool. Always `tool_search`. - A double click action. + - `"tool_search"` - - `Drag object { path, type, keys }` + - `description: optional string` - A drag action. + Description shown to the model for a client-executed tool search tool. - - `Keypress object { keys, type }` + - `execution: optional "server" or "client"` - A collection of keypresses the model would like to perform. + Whether tool search is executed by the server or by the client. - - `Move object { type, x, y, keys }` + - `"server"` - A mouse move action. + - `"client"` - - `Screenshot object { type }` + - `parameters: optional unknown` - A screenshot action. + Parameter schema for a client-executed tool search tool. - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - A scroll action. + 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 object { text, type }` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - An action to type in text. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `Wait object { type }` + - `"web_search_preview"` - A wait action. + - `"web_search_preview_2025_03_11"` - - `agent: optional object { agent_name }` + - `search_content_types: optional array of "text" or "image"` - The agent that produced this item. + - `"text"` - - `agent_name: string` + - `"image"` - The canonical name of the agent that produced this item. + - `search_context_size: optional "low" or "medium" or "high"` - - `ComputerCallOutput object { id, call_id, output, 5 more }` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `id: string` + - `"low"` - The unique ID of the computer call tool output. + - `"medium"` - - `call_id: string` + - `"high"` - The ID of the computer tool call that produced the output. + - `user_location: optional object { type, city, country, 2 more }` - - `output: BetaResponseComputerToolCallOutputScreenshot` + The user's location. - A computer screenshot image used with the computer use tool. + - `type: "approximate"` - - `type: "computer_screenshot"` + The type of location approximation. Always `approximate`. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `"approximate"` - - `"computer_screenshot"` + - `city: optional string` - - `file_id: optional string` + Free text input for the city of the user, e.g. `San Francisco`. - The identifier of an uploaded file that contains the screenshot. + - `country: optional string` - - `image_url: optional string` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The URL of the screenshot image. + - `region: optional string` - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + Free text input for the region of the user, e.g. `California`. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `timezone: optional string` - - `"completed"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"incomplete"` + - `ApplyPatch object { type, allowed_callers }` - - `"failed"` + Allows the assistant to create, delete, or update files using unified diffs. - - `"in_progress"` + - `type: "apply_patch"` - - `type: "computer_call_output"` + The type of the tool. Always `apply_patch`. - The type of the computer tool call output. Always `computer_call_output`. + - `"apply_patch"` - - `"computer_call_output"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + The tool invocation context(s). - The safety checks reported by the API that have been acknowledged by the - developer. + - `"direct"` - - `id: string` + - `"programmatic"` - The ID of the pending safety check. + - `type: "additional_tools"` - - `code: optional string` + The item type. Always `additional_tools`. - The type of the pending safety check. + - `"additional_tools"` - - `message: optional string` + - `id: optional string` - Details about the pending safety check. + The unique ID of this additional tools item. - `agent: optional object { agent_name }` @@ -54208,10 +51530,6 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` - - The identifier of the actor that created the item. - - `Reasoning object { id, summary, type, 4 more }` A description of the chain of thought used by a reasoning model while generating @@ -54282,17 +51600,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `Compaction object { id, encrypted_content, type, 2 more }` + - `Compaction object { encrypted_content, type, id, agent }` A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - - `id: string` - - The unique ID of the compaction item. - - `encrypted_content: string` - The encrypted content that was produced by compaction. + The encrypted content of the compaction summary. - `type: "compaction"` @@ -54300,6 +51614,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"compaction"` + - `id: optional string` + + The ID of the compaction item. + - `agent: optional object { agent_name }` The agent that produced this item. @@ -54308,9 +51626,43 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` + - `ImageGenerationCall object { id, result, status, 2 more }` - The identifier of the actor that created the item. + An image generation request made by the model. + + - `id: string` + + The unique ID of the image generation call. + + - `result: string` + + The generated image encoded in base64. + + - `status: "in_progress" or "completed" or "generating" or "failed"` + + The status of the image generation call. + + - `"in_progress"` + + - `"completed"` + + - `"generating"` + + - `"failed"` + + - `type: "image_generation_call"` + + The type of the image generation call. Always `image_generation_call`. + + - `"image_generation_call"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. - `CodeInterpreterCall object { id, code, container_id, 4 more }` @@ -54491,13 +51843,9 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `ShellCall object { id, action, call_id, 6 more }` - - A tool call that executes one or more shell commands in a managed environment. - - - `id: string` + - `ShellCall object { action, call_id, type, 5 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 }` @@ -54505,60 +51853,30 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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: BetaResponseLocalEnvironment or BetaResponseContainerReference` - - Represents the use of a local environment to perform shell actions. - - - `BetaResponseLocalEnvironment object { type }` - - Represents the use of a local environment to perform shell actions. - - - `type: "local"` - - The environment type. Always `local`. - - - `"local"` - - - `BetaResponseContainerReference 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. + - `agent: optional object { agent_name }` The agent that produced this item. @@ -54575,6 +51893,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "direct"` + The caller type. Always `direct`. + - `"direct"` - `Program object { caller_id, type }` @@ -54585,35 +51905,43 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "program"` + The caller type. Always `program`. + - `"program"` - - `created_by: optional string` + - `environment: optional BetaLocalEnvironment or BetaContainerReference` - 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, 6 more }` + - `BetaLocalEnvironment object { type, skills }` - The output of a shell tool call that was emitted. + - `BetaContainerReference 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, 5 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 BetaResponseFunctionShellCallOutputContent` + + 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 }` @@ -54631,7 +51959,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `exit_code: number` - Exit code from the shell process. + The exit code returned by the shell process. - `type: "exit"` @@ -54641,32 +51969,22 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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. + - `agent: optional object { agent_name }` The agent that produced this item. @@ -54683,6 +52001,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "direct"` + The caller type. Always `direct`. + - `"direct"` - `Program object { caller_id, type }` @@ -54693,19 +52013,27 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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, 5 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, 4 more }` + + A tool call representing a request to create, delete, or update files using diff patches. - `call_id: string` @@ -54713,55 +52041,55 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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"` @@ -54779,6 +52107,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"apply_patch_call"` + - `id: optional string` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `agent: optional object { agent_name }` The agent that produced this item. @@ -54795,6 +52127,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "direct"` + The caller type. Always `direct`. + - `"direct"` - `Program object { caller_id, type }` @@ -54805,19 +52139,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "program"` - - `"program"` - - - `created_by: optional string` - - The ID of the entity that created this tool call. - - - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` + The caller type. Always `program`. - The output emitted by an apply patch tool call. + - `"program"` - - `id: string` + - `ApplyPatchCallOutput object { call_id, status, type, 4 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` @@ -54837,6 +52165,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"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. + - `agent: optional object { agent_name }` The agent that produced this item. @@ -54853,6 +52185,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "direct"` + The caller type. Always `direct`. + - `"direct"` - `Program object { caller_id, type }` @@ -54863,15 +52197,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "program"` - - `"program"` - - - `created_by: optional string` + The caller type. Always `program`. - The ID of the entity that created this tool call output. + - `"program"` - `output: optional string` - Optional textual output returned by the apply patch tool. + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - `McpListTools object { id, server_label, tools, 3 more }` @@ -54957,14 +52289,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` + - `McpApprovalResponse object { approval_request_id, approve, type, 3 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. @@ -54979,6 +52307,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"mcp_approval_response"` + - `id: optional string` + + The unique ID of the approval response + - `agent: optional object { agent_name }` The agent that produced this item. @@ -55052,64 +52384,6 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"failed"` - - `CustomToolCall object { call_id, input, name, 5 more }` - - A call to a custom tool created by the model. - - - `call_id: string` - - An identifier used to map this custom tool call to a tool call output. - - - `input: string` - - The input for the custom tool call generated by the model. - - - `name: string` - - The name of the custom tool being called. - - - `type: "custom_tool_call"` - - The type of the custom tool call. Always `custom_tool_call`. - - - `"custom_tool_call"` - - - `id: optional string` - - The unique ID of the custom tool call in the OpenAI platform. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. - - - `Direct object { type }` - - - `type: "direct"` - - - `"direct"` - - - `Program object { caller_id, type }` - - - `caller_id: string` - - The call ID of the program item that produced this tool call. - - - `type: "program"` - - - `"program"` - - - `namespace: optional string` - - The namespace of the custom tool being called. - - `CustomToolCallOutput object { call_id, output, type, 3 more }` The output of a custom tool call from your code, being sent back to the model. @@ -55185,1170 +52459,1046 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"program"` - - `usage: BetaResponseUsage` - - Token accounting for the compaction pass, including cached, reasoning, and total tokens. - - - `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. - -### Beta Computer Action - -- `BetaComputerAction = object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` - - A click action. - - - `Click object { button, type, x, 2 more }` - - A click action. - - - `button: "left" or "right" or "wheel" or 2 more` - - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - - `"left"` - - - `"right"` - - - `"wheel"` - - - `"back"` - - - `"forward"` - - - `type: "click"` - - Specifies the event type. For a click action, this property is always `click`. - - - `"click"` - - - `x: number` - - The x-coordinate where the click occurred. - - - `y: number` - - The y-coordinate where the click occurred. - - - `keys: optional array of string` - - The keys being held while clicking. - - - `DoubleClick object { keys, type, x, y }` - - A double click action. - - - `keys: array of string` - - The keys being held while double-clicking. - - - `type: "double_click"` - - Specifies the event type. For a double click action, this property is always set to `double_click`. - - - `"double_click"` - - - `x: number` - - The x-coordinate where the double click occurred. - - - `y: number` - - The y-coordinate where the double click occurred. - - - `Drag object { path, type, keys }` - - A drag action. - - - `path: array of object { x, y }` - - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` - - - `x: number` - - The x-coordinate. - - - `y: number` + - `CustomToolCall object { call_id, input, name, 5 more }` - The y-coordinate. + A call to a custom tool created by the model. - - `type: "drag"` + - `call_id: string` - Specifies the event type. For a drag action, this property is always set to `drag`. + An identifier used to map this custom tool call to a tool call output. - - `"drag"` + - `input: string` - - `keys: optional array of string` + The input for the custom tool call generated by the model. - The keys being held while dragging the mouse. + - `name: string` - - `Keypress object { keys, type }` + The name of the custom tool being called. - A collection of keypresses the model would like to perform. + - `type: "custom_tool_call"` - - `keys: array of string` + The type of the custom tool call. Always `custom_tool_call`. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `"custom_tool_call"` - - `type: "keypress"` + - `id: optional string` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + The unique ID of the custom tool call in the OpenAI platform. - - `"keypress"` + - `agent: optional object { agent_name }` - - `Move object { type, x, y, keys }` + The agent that produced this item. - A mouse move action. + - `agent_name: string` - - `type: "move"` + The canonical name of the agent that produced this item. - Specifies the event type. For a move action, this property is always set to `move`. + - `caller: optional object { type } or object { caller_id, type }` - - `"move"` + The execution context that produced this tool call. - - `x: number` + - `Direct object { type }` - The x-coordinate to move to. + - `type: "direct"` - - `y: number` + - `"direct"` - The y-coordinate to move to. + - `Program object { caller_id, type }` - - `keys: optional array of string` + - `caller_id: string` - The keys being held while moving the mouse. + The call ID of the program item that produced this tool call. - - `Screenshot object { type }` + - `type: "program"` - A screenshot action. + - `"program"` - - `type: "screenshot"` + - `namespace: optional string` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + The namespace of the custom tool being called. - - `"screenshot"` + - `CompactionTrigger object { type, agent }` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + Compacts the current context. Must be the final input item. - A scroll action. + - `type: "compaction_trigger"` - - `scroll_x: number` + The type of the item. Always `compaction_trigger`. - The horizontal scroll distance. + - `"compaction_trigger"` - - `scroll_y: number` + - `agent: optional object { agent_name }` - The vertical scroll distance. + The agent that produced this item. - - `type: "scroll"` + - `agent_name: string` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + The canonical name of the agent that produced this item. - - `"scroll"` + - `ItemReference object { id, agent, type }` - - `x: number` + An internal identifier for an item to reference. - The x-coordinate where the scroll occurred. + - `id: string` - - `y: number` + The ID of the item to reference. - The y-coordinate where the scroll occurred. + - `agent: optional object { agent_name }` - - `keys: optional array of string` + The agent that produced this item. - The keys being held while scrolling. + - `agent_name: string` - - `Type object { text, type }` + The canonical name of the agent that produced this item. - An action to type in text. + - `type: optional "item_reference"` - - `text: string` + The type of item to reference. Always `item_reference`. - The text to type. + - `"item_reference"` - - `type: "type"` + - `Program object { id, call_id, code, 3 more }` - Specifies the event type. For a type action, this property is always set to `type`. + - `id: string` - - `"type"` + The unique ID of this program item. - - `Wait object { type }` + - `call_id: string` - A wait action. + The stable call ID of the program item. - - `type: "wait"` + - `code: string` - Specifies the event type. For a wait action, this property is always set to `wait`. + The JavaScript source executed by programmatic tool calling. - - `"wait"` + - `fingerprint: string` -### Beta Computer Action List + Opaque program replay fingerprint that must be round-tripped. -- `BetaComputerActionList = array of BetaComputerAction` + - `type: "program"` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + The item type. Always `program`. - - `Click object { button, type, x, 2 more }` + - `"program"` - A click action. + - `agent: optional object { agent_name }` - - `button: "left" or "right" or "wheel" or 2 more` + The agent that produced this item. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `agent_name: string` - - `"left"` + The canonical name of the agent that produced this item. - - `"right"` + - `ProgramOutput object { id, call_id, result, 3 more }` - - `"wheel"` + - `id: string` - - `"back"` + The unique ID of this program output item. - - `"forward"` + - `call_id: string` - - `type: "click"` + The call ID of the program item. - Specifies the event type. For a click action, this property is always `click`. + - `result: string` - - `"click"` + The result produced by the program item. - - `x: number` + - `status: "completed" or "incomplete"` - The x-coordinate where the click occurred. + The terminal status of the program output. - - `y: number` + - `"completed"` - The y-coordinate where the click occurred. + - `"incomplete"` - - `keys: optional array of string` + - `type: "program_output"` - The keys being held while clicking. + The item type. Always `program_output`. - - `DoubleClick object { keys, type, x, y }` + - `"program_output"` - A double click action. + - `agent: optional object { agent_name }` - - `keys: array of string` + The agent that produced this item. - The keys being held while double-clicking. + - `agent_name: string` - - `type: "double_click"` + The canonical name of the agent that produced this item. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `metadata: map[string]` - - `"double_click"` + 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. - - `x: number` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The x-coordinate where the double click occurred. + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - - `y: number` + 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. - The y-coordinate where the double click occurred. + - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` - - `Drag object { path, type, keys }` + 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. - A drag action. + - `"gpt-5.6-sol"` - - `path: array of object { x, y }` + - `"gpt-5.6-terra"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `"gpt-5.6-luna"` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `"gpt-5.4"` - - `x: number` + - `"gpt-5.4-mini"` - The x-coordinate. + - `"gpt-5.4-nano"` - - `y: number` + - `"gpt-5.4-mini-2026-03-17"` - The y-coordinate. + - `"gpt-5.4-nano-2026-03-17"` - - `type: "drag"` + - `"gpt-5.3-chat-latest"` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `"gpt-5.2"` - - `"drag"` + - `"gpt-5.2-2025-12-11"` - - `keys: optional array of string` + - `"gpt-5.2-chat-latest"` - The keys being held while dragging the mouse. + - `"gpt-5.2-pro"` - - `Keypress object { keys, type }` + - `"gpt-5.2-pro-2025-12-11"` - A collection of keypresses the model would like to perform. + - `"gpt-5.1"` - - `keys: array of string` + - `"gpt-5.1-2025-11-13"` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `"gpt-5.1-codex"` - - `type: "keypress"` + - `"gpt-5.1-mini"` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `"gpt-5.1-chat-latest"` - - `"keypress"` + - `"gpt-5"` - - `Move object { type, x, y, keys }` + - `"gpt-5-mini"` - A mouse move action. + - `"gpt-5-nano"` - - `type: "move"` + - `"gpt-5-2025-08-07"` - Specifies the event type. For a move action, this property is always set to `move`. + - `"gpt-5-mini-2025-08-07"` - - `"move"` + - `"gpt-5-nano-2025-08-07"` - - `x: number` + - `"gpt-5-chat-latest"` - The x-coordinate to move to. + - `"gpt-4.1"` - - `y: number` + - `"gpt-4.1-mini"` - The y-coordinate to move to. + - `"gpt-4.1-nano"` - - `keys: optional array of string` + - `"gpt-4.1-2025-04-14"` - The keys being held while moving the mouse. + - `"gpt-4.1-mini-2025-04-14"` - - `Screenshot object { type }` + - `"gpt-4.1-nano-2025-04-14"` - A screenshot action. + - `"o4-mini"` - - `type: "screenshot"` + - `"o4-mini-2025-04-16"` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `"o3"` - - `"screenshot"` + - `"o3-2025-04-16"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `"o3-mini"` - A scroll action. + - `"o3-mini-2025-01-31"` - - `scroll_x: number` + - `"o1"` - The horizontal scroll distance. + - `"o1-2024-12-17"` - - `scroll_y: number` + - `"o1-preview"` - The vertical scroll distance. + - `"o1-preview-2024-09-12"` - - `type: "scroll"` + - `"o1-mini"` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `"o1-mini-2024-09-12"` - - `"scroll"` + - `"gpt-4o"` - - `x: number` + - `"gpt-4o-2024-11-20"` - The x-coordinate where the scroll occurred. + - `"gpt-4o-2024-08-06"` - - `y: number` + - `"gpt-4o-2024-05-13"` - The y-coordinate where the scroll occurred. + - `"gpt-4o-audio-preview"` - - `keys: optional array of string` + - `"gpt-4o-audio-preview-2024-10-01"` - The keys being held while scrolling. + - `"gpt-4o-audio-preview-2024-12-17"` - - `Type object { text, type }` + - `"gpt-4o-audio-preview-2025-06-03"` - An action to type in text. + - `"gpt-4o-mini-audio-preview"` - - `text: string` + - `"gpt-4o-mini-audio-preview-2024-12-17"` - The text to type. + - `"gpt-4o-search-preview"` - - `type: "type"` + - `"gpt-4o-mini-search-preview"` - Specifies the event type. For a type action, this property is always set to `type`. + - `"gpt-4o-search-preview-2025-03-11"` - - `"type"` + - `"gpt-4o-mini-search-preview-2025-03-11"` - - `Wait object { type }` + - `"chatgpt-4o-latest"` - A wait action. + - `"codex-mini-latest"` - - `type: "wait"` + - `"gpt-4o-mini"` - Specifies the event type. For a wait action, this property is always set to `wait`. + - `"gpt-4o-mini-2024-07-18"` - - `"wait"` + - `"gpt-4-turbo"` -### Beta Container Auto + - `"gpt-4-turbo-2024-04-09"` -- `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `"gpt-4-0125-preview"` - - `type: "container_auto"` + - `"gpt-4-turbo-preview"` - Automatically creates a container for this request + - `"gpt-4-1106-preview"` - - `"container_auto"` + - `"gpt-4-vision-preview"` - - `file_ids: optional array of string` + - `"gpt-4"` - An optional list of uploaded files to make available to your code. + - `"gpt-4-0314"` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `"gpt-4-0613"` - The memory limit for the container. + - `"gpt-4-32k"` - - `"1g"` + - `"gpt-4-32k-0314"` - - `"4g"` + - `"gpt-4-32k-0613"` - - `"16g"` + - `"gpt-3.5-turbo"` - - `"64g"` + - `"gpt-3.5-turbo-16k"` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `"gpt-3.5-turbo-0301"` - Network access policy for the container. + - `"gpt-3.5-turbo-0613"` - - `BetaContainerNetworkPolicyDisabled object { type }` + - `"gpt-3.5-turbo-1106"` - - `type: "disabled"` + - `"gpt-3.5-turbo-0125"` - Disable outbound network access. Always `disabled`. + - `"gpt-3.5-turbo-16k-0613"` - - `"disabled"` + - `"o1-pro"` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `"o1-pro-2025-03-19"` - - `allowed_domains: array of string` + - `"o3-pro"` - A list of allowed domains when type is `allowlist`. + - `"o3-pro-2025-06-10"` - - `type: "allowlist"` + - `"o3-deep-research"` - Allow outbound network access only to specified domains. Always `allowlist`. + - `"o3-deep-research-2025-06-26"` - - `"allowlist"` + - `"o4-mini-deep-research"` - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + - `"o4-mini-deep-research-2025-06-26"` - Optional domain-scoped secrets for allowlisted domains. + - `"computer-use-preview"` - - `domain: string` + - `"computer-use-preview-2025-03-11"` - The domain associated with the secret. + - `"gpt-5-codex"` - - `name: string` + - `"gpt-5-pro"` - The name of the secret to inject for the domain. + - `"gpt-5-pro-2025-10-06"` - - `value: string` + - `"gpt-5.1-codex-max"` - The secret value to inject for the domain. + - `string` - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + - `object: "response"` - An optional list of skills referenced by id or inline data. + The object type of this resource - always set to `response`. - - `BetaSkillReference object { skill_id, type, version }` + - `"response"` - - `skill_id: string` + - `output: array of BetaResponseOutputItem` - The ID of the referenced skill. + An array of content items generated by the model. - - `type: "skill_reference"` + - 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. - References a skill created with the /v1/skills endpoint. + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - - `"skill_reference"` + An output message from the model. - - `version: optional string` + - `FileSearchCall object { id, queries, status, 3 more }` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - - `BetaInlineSkill object { description, name, source, type }` + - `id: string` - - `description: string` + The unique ID of the file search tool call. - The description of the skill. + - `queries: array of string` - - `name: string` + The queries used to search for files. - The name of the skill. + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `source: BetaInlineSkillSource` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - Inline skill payload + - `"in_progress"` - - `data: string` + - `"searching"` - Base64-encoded skill zip bundle. + - `"completed"` - - `media_type: "application/zip"` + - `"incomplete"` - The media type of the inline skill payload. Must be `application/zip`. + - `"failed"` - - `"application/zip"` + - `type: "file_search_call"` - - `type: "base64"` + The type of the file search tool call. Always `file_search_call`. - The type of the inline skill source. Must be `base64`. + - `"file_search_call"` - - `"base64"` + - `agent: optional object { agent_name }` - - `type: "inline"` + The agent that produced this item. - Defines an inline skill for this request. + - `agent_name: string` - - `"inline"` + The canonical name of the agent that produced this item. -### Beta Container Network Policy Allowlist + - `results: optional array of object { attributes, file_id, filename, 2 more }` -- `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + The results of the file search tool call. - - `allowed_domains: array of string` + - `attributes: optional map[string or number or boolean]` - A list of allowed domains when type is `allowlist`. + 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. - - `type: "allowlist"` + - `string` - Allow outbound network access only to specified domains. Always `allowlist`. + - `number` - - `"allowlist"` + - `boolean` - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + - `file_id: optional string` - Optional domain-scoped secrets for allowlisted domains. + The unique ID of the file. - - `domain: string` + - `filename: optional string` - The domain associated with the secret. + The name of the file. - - `name: string` + - `score: optional number` - The name of the secret to inject for the domain. + The relevance score of the file - a value between 0 and 1. - - `value: string` + - `text: optional string` - The secret value to inject for the domain. + The text that was retrieved from the file. -### Beta Container Network Policy Disabled + - `FunctionCall object { arguments, call_id, name, 6 more }` -- `BetaContainerNetworkPolicyDisabled object { type }` + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `type: "disabled"` + - `arguments: string` - Disable outbound network access. Always `disabled`. + A JSON string of the arguments to pass to the function. - - `"disabled"` + - `call_id: string` -### Beta Container Network Policy Domain Secret + The unique ID of the function tool call generated by the model. -- `BetaContainerNetworkPolicyDomainSecret object { domain, name, value }` + - `name: string` - - `domain: string` + The name of the function to run. - The domain associated with the secret. + - `type: "function_call"` - - `name: string` + The type of the function tool call. Always `function_call`. - The name of the secret to inject for the domain. + - `"function_call"` - - `value: string` + - `id: optional string` - The secret value to inject for the domain. + The unique ID of the function tool call. -### Beta Container Reference + - `agent: optional object { agent_name }` -- `BetaContainerReference object { container_id, type }` + The agent that produced this item. - - `container_id: string` + - `agent_name: string` - The ID of the referenced container. + The canonical name of the agent that produced this item. - - `type: "container_reference"` + - `caller: optional object { type } or object { caller_id, type }` - References a container created with the /v1/containers endpoint + The execution context that produced this tool call. - - `"container_reference"` + - `Direct object { type }` -### Beta Easy Input Message + - `type: "direct"` -- `BetaEasyInputMessage object { content, role, phase, type }` + - `"direct"` - 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. + - `Program object { caller_id, type }` - - `content: string or BetaResponseInputMessageContentList` + - `caller_id: string` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + The call ID of the program item that produced this tool call. - - `TextInput = string` + - `type: "program"` - A text input to the model. + - `"program"` - - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` + - `namespace: optional string` - A list of one or many input items to the model, containing different content - types. + The namespace of the function to run. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `status: optional "in_progress" or "completed" or "incomplete"` - A text input to the model. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `text: string` + - `"in_progress"` - The text input to the model. + - `"completed"` - - `type: "input_text"` + - `"incomplete"` - The type of the input item. Always `input_text`. + - `FunctionCallOutput object { id, call_id, output, 5 more }` - - `"input_text"` + - `id: string` - - `prompt_cache_breakpoint: optional object { mode }` + The unique ID of the function call tool 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. + - `call_id: string` - - `mode: "explicit"` + The unique ID of the function tool call generated by the model. - The breakpoint mode. Always `explicit`. + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `"explicit"` + The output from the function call generated by your code. + Can be a string or an list of output content. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `StringOutput = string` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + A string of the output of the function call. - - `detail: "low" or "high" or "auto" or "original"` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Text, image, or file output of the function call. - - `"low"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `"high"` + A text input to the model. - - `"auto"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `"original"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `type: "input_image"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - The type of the input item. Always `input_image`. + A file input to the model. - - `"input_image"` + - `status: "in_progress" or "completed" or "incomplete"` - - `file_id: optional string` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The ID of the file to be sent to the model. + - `"in_progress"` - - `image_url: optional string` + - `"completed"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `"incomplete"` - - `prompt_cache_breakpoint: optional object { mode }` + - `type: "function_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. + The type of the function tool call output. Always `function_call_output`. - - `mode: "explicit"` + - `"function_call_output"` - The breakpoint mode. Always `explicit`. + - `agent: optional object { agent_name }` - - `"explicit"` + The agent that produced this item. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `agent_name: string` - A file input to the model. + The canonical name of the agent that produced this item. - - `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`. + The caller type. Always `direct`. - - `"auto"` + - `"direct"` - - `"low"` + - `Program object { caller_id, type }` - - `"high"` + - `caller_id: string` - - `file_data: optional string` + The call ID of the program item that produced this tool call. - The content of the file to be sent to the model. + - `type: "program"` - - `file_id: optional string` + The caller type. Always `program`. - The ID of the file to be sent to the model. + - `"program"` - - `file_url: optional string` + - `created_by: optional string` - The URL of the file to be sent to the model. + The identifier of the actor that created the item. - - `filename: optional string` + - `AgentMessage object { id, author, content, 3 more }` - The name of the file to be sent to the model. + - `id: string` - - `prompt_cache_breakpoint: optional object { mode }` + The unique ID of the agent message. - 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. + - `author: string` - - `mode: "explicit"` + The sending agent identity. - The breakpoint mode. Always `explicit`. + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - - `"explicit"` + Encrypted content sent between agents. - - `role: "user" or "assistant" or "system" or "developer"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + A text input to the model. - - `"user"` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - - `"assistant"` + A text output from the model. - - `"system"` + - `Text object { text, type }` - - `"developer"` + A text content. - - `phase: optional "commentary" or "final_answer"` + - `text: 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. + - `type: "text"` - - `"commentary"` + - `"text"` - - `"final_answer"` + - `SummaryText object { text, type }` - - `type: optional "message"` + A summary text from the model. - The type of the message input. Always `message`. + - `text: string` - - `"message"` + A summary of the reasoning output from the model so far. -### Beta Inline Skill + - `type: "summary_text"` -- `BetaInlineSkill object { description, name, source, type }` + The type of the object. Always `summary_text`. - - `description: string` + - `"summary_text"` - The description of the skill. + - `ReasoningText object { text, type }` - - `name: string` + Reasoning text from the model. - The name of the skill. + - `text: string` - - `source: BetaInlineSkillSource` + The reasoning text from the model. - Inline skill payload + - `type: "reasoning_text"` - - `data: string` + The type of the reasoning text. Always `reasoning_text`. - Base64-encoded skill zip bundle. + - `"reasoning_text"` - - `media_type: "application/zip"` + - `BetaResponseOutputRefusal object { refusal, type }` - The media type of the inline skill payload. Must be `application/zip`. + A refusal from the model. - - `"application/zip"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `type: "base64"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - The type of the inline skill source. Must be `base64`. + - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` - - `"base64"` + A screenshot of a computer. - - `type: "inline"` + - `detail: "low" or "high" or "auto" or "original"` - Defines an inline skill for this request. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"inline"` + - `"low"` -### Beta Inline Skill Source + - `"high"` -- `BetaInlineSkillSource object { data, media_type, type }` + - `"auto"` - Inline skill payload + - `"original"` - - `data: string` + - `file_id: string` - Base64-encoded skill zip bundle. + The identifier of an uploaded file that contains the screenshot. - - `media_type: "application/zip"` + - `image_url: string` - The media type of the inline skill payload. Must be `application/zip`. + The URL of the screenshot image. - - `"application/zip"` + - `type: "computer_screenshot"` - - `type: "base64"` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - The type of the inline skill source. Must be `base64`. + - `"computer_screenshot"` - - `"base64"` + - `prompt_cache_breakpoint: optional object { mode }` -### Beta Local Environment + 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. -- `BetaLocalEnvironment object { type, skills }` + - `mode: "explicit"` - - `type: "local"` + The breakpoint mode. Always `explicit`. - Use a local computer environment. + - `"explicit"` - - `"local"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `skills: optional array of BetaLocalSkill` + A file input to the model. - An optional list of skills. + - `EncryptedContent object { encrypted_content, type }` - - `description: string` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - The description of the skill. + - `encrypted_content: string` - - `name: string` + Opaque encrypted content. - The name of the skill. + - `type: "encrypted_content"` - - `path: string` + The type of the input item. Always `encrypted_content`. - The path to the directory containing the skill. + - `"encrypted_content"` -### Beta Local Skill + - `recipient: string` -- `BetaLocalSkill object { description, name, path }` + The destination agent identity. - - `description: string` + - `type: "agent_message"` - The description of the skill. + The type of the item. Always `agent_message`. - - `name: string` + - `"agent_message"` - The name of the skill. + - `agent: optional object { agent_name }` - - `path: string` + The agent that produced this item. - The path to the directory containing the skill. + - `agent_name: string` -### Beta Response + The canonical name of the agent that produced this item. -- `BetaResponse object { id, created_at, error, 32 more }` + - `MultiAgentCall object { id, action, arguments, 3 more }` - `id: string` - Unique identifier for this Response. - - - `created_at: number` + The unique ID of the multi-agent call item. - Unix timestamp (in seconds) of when this Response was created. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `error: BetaResponseError` + The multi-agent action to execute. - An error object returned when the model fails to generate a Response. + - `"spawn_agent"` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 17 more` + - `"interrupt_agent"` - The error code for the response. + - `"list_agents"` - - `"server_error"` + - `"send_message"` - - `"rate_limit_exceeded"` + - `"followup_task"` - - `"invalid_prompt"` + - `"wait_agent"` - - `"data_residency_mismatch"` + - `arguments: string` - - `"bio_policy"` + The JSON string of arguments generated for the action. - - `"vector_store_timeout"` + - `call_id: string` - - `"invalid_image"` + The unique ID linking this call to its output. - - `"invalid_image_format"` + - `type: "multi_agent_call"` - - `"invalid_base64_image"` + The type of the multi-agent call. Always `multi_agent_call`. - - `"invalid_image_url"` + - `"multi_agent_call"` - - `"image_too_large"` + - `agent: optional object { agent_name }` - - `"image_too_small"` + The agent that produced this item. - - `"image_parse_error"` + - `agent_name: string` - - `"image_content_policy_violation"` + The canonical name of the agent that produced this item. - - `"invalid_image_mode"` + - `MultiAgentCallOutput object { id, action, call_id, 3 more }` - - `"image_file_too_large"` + - `id: string` - - `"unsupported_image_media_type"` + The unique ID of the multi-agent call output item. - - `"empty_image_file"` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `"failed_to_download_image"` + The multi-agent action that produced this result. - - `"image_file_not_found"` + - `"spawn_agent"` - - `message: string` + - `"interrupt_agent"` - A human-readable description of the error. + - `"list_agents"` - - `incomplete_details: object { reason }` + - `"send_message"` - Details about why the response is incomplete. + - `"followup_task"` - - `reason: optional "max_output_tokens" or "content_filter"` + - `"wait_agent"` - The reason why the response is incomplete. + - `call_id: string` - - `"max_output_tokens"` + The unique ID of the multi-agent call. - - `"content_filter"` + - `output: array of BetaResponseOutputText` - - `instructions: string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + Text output returned by the multi-agent action. - A system (or developer) message inserted into the model's context. + - `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 }` - 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. + The annotations of the text output. - - `string` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - A text input to the model, equivalent to a text input with the - `developer` role. + - `text: string` - - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + The text output from the model. - A list of one or many input items to the model, containing - different content types. + - `type: "output_text"` - - `BetaEasyInputMessage object { content, role, phase, type }` + The type of the output text. Always `output_text`. - 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: "multi_agent_call_output"` - - `content: string or BetaResponseInputMessageContentList` + The type of the multi-agent result. Always `multi_agent_call_output`. - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `"multi_agent_call_output"` - - `TextInput = string` + - `agent: optional object { agent_name }` - A text input to the model. + The agent that produced this item. - - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` + - `agent_name: string` - A list of one or many input items to the model, containing different content - types. + The canonical name of the agent that produced this item. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `WebSearchCall object { id, action, status, 2 more }` - A text input to the model. + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `text: string` + - `id: string` - The text input to the model. + The unique ID of the web search tool call. - - `type: "input_text"` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - The type of the input item. Always `input_text`. + 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). - - `"input_text"` + - `Search object { type, queries, query, sources }` - - `prompt_cache_breakpoint: optional object { mode }` + Action type "search" - Performs a web search query. - 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: "search"` - - `mode: "explicit"` + The action type. - The breakpoint mode. Always `explicit`. + - `"search"` - - `"explicit"` + - `queries: optional array of string` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + The search queries. - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `query: optional string` - - `detail: "low" or "high" or "auto" or "original"` + The search query. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `sources: optional array of object { type, url }` - - `"low"` + The sources used in the search. - - `"high"` + - `type: "url"` - - `"auto"` + The type of source. Always `url`. - - `"original"` + - `"url"` - - `type: "input_image"` + - `url: string` - The type of the input item. Always `input_image`. + The URL of the source. - - `"input_image"` + - `OpenPage object { type, url }` - - `file_id: optional string` + Action type "open_page" - Opens a specific URL from search results. - The ID of the file to be sent to the model. + - `type: "open_page"` - - `image_url: optional string` + The action type. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `"open_page"` - - `prompt_cache_breakpoint: optional object { mode }` + - `url: 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 URL opened by the model. - - `mode: "explicit"` + - `FindInPage object { pattern, type, url }` - The breakpoint mode. Always `explicit`. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `"explicit"` + - `pattern: string` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + The pattern or text to search for within the page. - A file input to the model. + - `type: "find_in_page"` - - `type: "input_file"` + The action type. - The type of the input item. Always `input_file`. + - `"find_in_page"` - - `"input_file"` + - `url: string` - - `detail: optional "auto" or "low" or "high"` + The URL of the page searched for the pattern. - 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`. + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `"auto"` + The status of the web search tool call. - - `"low"` + - `"in_progress"` - - `"high"` + - `"searching"` - - `file_data: optional string` + - `"completed"` - The content of the file to be sent to the model. + - `"failed"` - - `file_id: optional string` + - `type: "web_search_call"` - The ID of the file to be sent to the model. + The type of the web search tool call. Always `web_search_call`. - - `file_url: optional string` + - `"web_search_call"` - The URL of the file to be sent to the model. + - `agent: optional object { agent_name }` - - `filename: optional string` + The agent that produced this item. - The name of the file to be sent to the model. + - `agent_name: string` - - `prompt_cache_breakpoint: optional object { mode }` + The canonical name of the agent that produced this item. - 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. + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - - `mode: "explicit"` + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - The breakpoint mode. Always `explicit`. + - `id: string` - - `"explicit"` + The unique ID of the computer call. - - `role: "user" or "assistant" or "system" or "developer"` + - `call_id: string` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + An identifier used when responding to the tool call with output. - - `"user"` + - `pending_safety_checks: array of object { id, code, message }` - - `"assistant"` + The pending safety checks for the computer call. - - `"system"` + - `id: string` - - `"developer"` + The ID of the pending safety check. - - `phase: optional "commentary" or "final_answer"` + - `code: optional string` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + The type of the pending safety check. - - `"commentary"` + - `message: optional string` - - `"final_answer"` + Details about the pending safety check. - - `type: optional "message"` + - `status: "in_progress" or "completed" or "incomplete"` - The type of the message input. Always `message`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"message"` + - `"in_progress"` - - `Message object { content, role, agent, 2 more }` + - `"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. + - `"incomplete"` - - `content: BetaResponseInputMessageContentList` + - `type: "computer_call"` - A list of one or many input items to the model, containing different content - types. + The type of the computer call. Always `computer_call`. - - `role: "user" or "system" or "developer"` + - `"computer_call"` - The role of the message input. One of `user`, `system`, or `developer`. + - `action: optional BetaComputerAction` - - `"user"` + A click action. - - `"system"` + - `actions: optional BetaComputerActionList` - - `"developer"` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - `agent: optional object { agent_name }` @@ -56358,201 +53508,197 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `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"` + - `ComputerCallOutput object { id, call_id, output, 5 more }` - The type of the message input. Always set to `message`. + - `id: string` - - `"message"` + The unique ID of the computer call tool output. - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + - `call_id: string` - An output message from the model. + The ID of the computer tool call that produced the output. - - `id: string` + - `output: BetaResponseComputerToolCallOutputScreenshot` - The unique ID of the output message. + A computer screenshot image used with the computer use tool. - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - The content of the output message. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `BetaResponseOutputText object { annotations, logprobs, text, type }` + - `"completed"` - A text output from the model. + - `"incomplete"` - - `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 }` + - `"failed"` - The annotations of the text output. + - `"in_progress"` - - `FileCitation object { file_id, filename, index, type }` + - `type: "computer_call_output"` - A citation to a file. + The type of the computer tool call output. Always `computer_call_output`. - - `file_id: string` + - `"computer_call_output"` - The ID of the file. + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `filename: string` + The safety checks reported by the API that have been acknowledged by the + developer. - The filename of the file cited. + - `id: string` - - `index: number` + The ID of the pending safety check. - The index of the file in the list of files. + - `code: optional string` - - `type: "file_citation"` + The type of the pending safety check. - The type of the file citation. Always `file_citation`. + - `message: optional string` - - `"file_citation"` + Details about the pending safety check. - - `URLCitation object { end_index, start_index, title, 2 more }` + - `agent: optional object { agent_name }` - A citation for a web resource used to generate a model response. + The agent that produced this item. - - `end_index: number` + - `agent_name: string` - The index of the last character of the URL citation in the message. + The canonical name of the agent that produced this item. - - `start_index: number` + - `created_by: optional string` - The index of the first character of the URL citation in the message. + The identifier of the actor that created the item. - - `title: string` + - `Reasoning object { id, summary, type, 4 more }` - The title of the web resource. + 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: "url_citation"` + - `id: string` - The type of the URL citation. Always `url_citation`. + The unique identifier of the reasoning content. - - `"url_citation"` + - `summary: array of object { text, type }` - - `url: string` + Reasoning summary content. - The URL of the web resource. + - `text: string` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + A summary of the reasoning output from the model so far. - A citation for a container file used to generate a model response. + - `type: "summary_text"` - - `container_id: string` + The type of the object. Always `summary_text`. - The ID of the container file. + - `"summary_text"` - - `end_index: number` + - `type: "reasoning"` - The index of the last character of the container file citation in the message. + The type of the object. Always `reasoning`. - - `file_id: string` + - `"reasoning"` - The ID of the file. + - `agent: optional object { agent_name }` - - `filename: string` + The agent that produced this item. - The filename of the container file cited. + - `agent_name: string` - - `start_index: number` + The canonical name of the agent that produced this item. - The index of the first character of the container file citation in the message. + - `content: optional array of object { text, type }` - - `type: "container_file_citation"` + Reasoning text content. - The type of the container file citation. Always `container_file_citation`. + - `text: string` - - `"container_file_citation"` + The reasoning text from the model. - - `FilePath object { file_id, index, type }` + - `type: "reasoning_text"` - A path to a file. + The type of the reasoning text. Always `reasoning_text`. - - `file_id: string` + - `"reasoning_text"` - The ID of the file. + - `encrypted_content: optional string` - - `index: number` + 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 index of the file in the list of files. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `type: "file_path"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The type of the file path. Always `file_path`. + - `"in_progress"` - - `"file_path"` + - `"completed"` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `"incomplete"` - - `token: string` + - `Program object { id, call_id, code, 3 more }` - - `bytes: array of number` + - `id: string` - - `logprob: number` + The unique ID of the program item. - - `top_logprobs: array of object { token, bytes, logprob }` + - `call_id: string` - - `token: string` + The stable call ID of the program item. - - `bytes: array of number` + - `code: string` - - `logprob: number` + The JavaScript source executed by programmatic tool calling. - - `text: string` + - `fingerprint: string` - The text output from the model. + Opaque program replay fingerprint that must be round-tripped. - - `type: "output_text"` + - `type: "program"` - The type of the output text. Always `output_text`. + The type of the item. Always `program`. - - `"output_text"` + - `"program"` - - `BetaResponseOutputRefusal object { refusal, type }` + - `agent: optional object { agent_name }` - A refusal from the model. + The agent that produced this item. - - `refusal: string` + - `agent_name: string` - The refusal explanation from the model. + The canonical name of the agent that produced this item. - - `type: "refusal"` + - `ProgramOutput object { id, call_id, result, 3 more }` - The type of the refusal. Always `refusal`. + - `id: string` - - `"refusal"` + The unique ID of the program output item. - - `role: "assistant"` + - `call_id: string` - The role of the output message. Always `assistant`. + The call ID of the program item. - - `"assistant"` + - `result: string` - - `status: "in_progress" or "completed" or "incomplete"` + The result produced by the program item. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `status: "completed" or "incomplete"` - - `"in_progress"` + The terminal status of the program output item. - `"completed"` - `"incomplete"` - - `type: "message"` + - `type: "program_output"` - The type of the output message. Always `message`. + The type of the item. Always `program_output`. - - `"message"` + - `"program_output"` - `agent: optional object { agent_name }` @@ -56562,49 +53708,43 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `phase: optional "commentary" or "final_answer"` + - `ToolSearchCall object { id, arguments, call_id, 5 more }` - 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. + - `id: string` - - `"commentary"` + The unique ID of the tool search call item. - - `"final_answer"` + - `arguments: unknown` - - `FileSearchCall object { id, queries, status, 3 more }` + Arguments used for the tool search call. - The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + - `call_id: string` - - `id: string` + The unique ID of the tool search call generated by the model. - The unique ID of the file search tool call. + - `execution: "server" or "client"` - - `queries: array of string` + Whether tool search was executed by the server or by the client. - The queries used to search for files. + - `"server"` - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `"client"` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `status: "in_progress" or "completed" or "incomplete"` - - `"in_progress"` + The status of the tool search call item that was recorded. - - `"searching"` + - `"in_progress"` - `"completed"` - `"incomplete"` - - `"failed"` - - - `type: "file_search_call"` + - `type: "tool_search_call"` - The type of the file search tool call. Always `file_search_call`. + The type of the item. Always `tool_search_call`. - - `"file_search_call"` + - `"tool_search_call"` - `agent: optional object { agent_name }` @@ -56614,1002 +53754,1036 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `results: optional array of object { attributes, file_id, filename, 2 more }` - - The results of the file search tool call. + - `created_by: optional string` - - `attributes: optional map[string or number or boolean]` + The identifier of the actor that created the 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. + - `ToolSearchOutput object { id, call_id, execution, 5 more }` - - `string` + - `id: string` - - `number` + The unique ID of the tool search output item. - - `boolean` + - `call_id: string` - - `file_id: optional string` + The unique ID of the tool search call generated by the model. - The unique ID of the file. + - `execution: "server" or "client"` - - `filename: optional string` + Whether tool search was executed by the server or by the client. - The name of the file. + - `"server"` - - `score: optional number` + - `"client"` - The relevance score of the file - a value between 0 and 1. + - `status: "in_progress" or "completed" or "incomplete"` - - `text: optional string` + The status of the tool search output item that was recorded. - The text that was retrieved from the file. + - `"in_progress"` - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + - `"completed"` - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + - `"incomplete"` - - `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 computer call. + The loaded tool definitions returned by tool search. - - `call_id: string` + - `Function object { name, parameters, strict, 5 more }` - An identifier used when responding to the tool call with 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). - - `pending_safety_checks: array of object { id, code, message }` + - `name: string` - The pending safety checks for the computer call. + The name of the function to call. - - `id: string` + - `parameters: map[unknown]` - The ID of the pending safety check. + A JSON schema object describing the parameters of the function. - - `code: optional string` + - `strict: boolean` - The type of the pending safety check. + Whether strict parameter validation is enforced for this function tool. - - `message: optional string` + - `type: "function"` - Details about the pending safety check. + The type of the function tool. Always `function`. - - `status: "in_progress" or "completed" or "incomplete"` + - `"function"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"in_progress"` + The tool invocation context(s). - - `"completed"` + - `"direct"` - - `"incomplete"` + - `"programmatic"` - - `type: "computer_call"` + - `defer_loading: optional boolean` - The type of the computer call. Always `computer_call`. + Whether this function is deferred and loaded via tool search. - - `"computer_call"` + - `description: optional string` - - `action: optional BetaComputerAction` + A description of the function. Used by the model to determine whether or not to call the function. - A click action. + - `output_schema: optional map[unknown]` - - `Click object { button, type, x, 2 more }` + A JSON schema object describing the JSON value encoded in string outputs for this function. - A click action. + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `button: "left" or "right" or "wheel" or 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). - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `type: "file_search"` - - `"left"` + The type of the file search tool. Always `file_search`. - - `"right"` + - `"file_search"` - - `"wheel"` + - `vector_store_ids: array of string` - - `"back"` + The IDs of the vector stores to search. - - `"forward"` + - `filters: optional object { key, type, value } or object { filters, type }` - - `type: "click"` + A filter to apply. - Specifies the event type. For a click action, this property is always `click`. + - `ComparisonFilter object { key, type, value }` - - `"click"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `x: number` + - `key: string` - The x-coordinate where the click occurred. + The key to compare against the value. - - `y: number` + - `type: "eq" or "ne" or "gt" or 5 more` - The y-coordinate where the click occurred. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `keys: optional array of string` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - The keys being held while clicking. + - `"eq"` - - `DoubleClick object { keys, type, x, y }` + - `"ne"` - A double click action. + - `"gt"` - - `keys: array of string` + - `"gte"` - The keys being held while double-clicking. + - `"lt"` - - `type: "double_click"` + - `"lte"` - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `"in"` - - `"double_click"` + - `"nin"` - - `x: number` + - `value: string or number or boolean or array of string or number` - The x-coordinate where the double click occurred. + The value to compare against the attribute key; supports string, number, or boolean types. - - `y: number` + - `string` - The y-coordinate where the double click occurred. + - `number` - - `Drag object { path, type, keys }` + - `boolean` - A drag action. + - `array of string or number` - - `path: array of object { x, y }` + - `string` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `number` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `CompoundFilter object { filters, type }` - - `x: number` + Combine multiple filters using `and` or `or`. - The x-coordinate. + - `filters: array of object { key, type, value } or unknown` - - `y: number` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The y-coordinate. + - `ComparisonFilter object { key, type, value }` - - `type: "drag"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `key: string` - - `"drag"` + The key to compare against the value. - - `keys: optional array of string` + - `type: "eq" or "ne" or "gt" or 5 more` - The keys being held while dragging the mouse. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `Keypress object { keys, type }` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - A collection of keypresses the model would like to perform. + - `"eq"` - - `keys: array of string` + - `"ne"` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `"gt"` - - `type: "keypress"` + - `"gte"` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `"lt"` - - `"keypress"` + - `"lte"` - - `Move object { type, x, y, keys }` + - `"in"` - A mouse move action. + - `"nin"` - - `type: "move"` + - `value: string or number or boolean or array of string or number` - Specifies the event type. For a move action, this property is always set to `move`. + The value to compare against the attribute key; supports string, number, or boolean types. - - `"move"` + - `string` - - `x: number` + - `number` - The x-coordinate to move to. + - `boolean` - - `y: number` + - `array of string or number` - The y-coordinate to move to. + - `string` - - `keys: optional array of string` + - `number` - The keys being held while moving the mouse. + - `unknown` - - `Screenshot object { type }` + - `type: "and" or "or"` - A screenshot action. + Type of operation: `and` or `or`. - - `type: "screenshot"` + - `"and"` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `"or"` - - `"screenshot"` + - `max_num_results: optional number` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - A scroll action. + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `scroll_x: number` + Ranking options for search. - The horizontal scroll distance. + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `scroll_y: number` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - The vertical scroll distance. + - `embedding_weight: number` - - `type: "scroll"` + The weight of the embedding in the reciprocal ranking fusion. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `text_weight: number` - - `"scroll"` + The weight of the text in the reciprocal ranking fusion. - - `x: number` + - `ranker: optional "auto" or "default-2024-11-15"` - The x-coordinate where the scroll occurred. + The ranker to use for the file search. - - `y: number` + - `"auto"` - The y-coordinate where the scroll occurred. + - `"default-2024-11-15"` - - `keys: optional array of string` + - `score_threshold: optional number` - The keys being held while scrolling. + 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. - - `Type object { text, type }` + - `Computer object { type }` - An action to type in text. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `text: string` + - `type: "computer"` - The text to type. + The type of the computer tool. Always `computer`. - - `type: "type"` + - `"computer"` - Specifies the event type. For a type action, this property is always set to `type`. + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `"type"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `Wait object { type }` + - `display_height: number` - A wait action. + The height of the computer display. - - `type: "wait"` + - `display_width: number` - Specifies the event type. For a wait action, this property is always set to `wait`. + The width of the computer display. - - `"wait"` + - `environment: "windows" or "mac" or "linux" or 2 more` - - `actions: optional BetaComputerActionList` + The type of computer environment to control. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `"windows"` - - `Click object { button, type, x, 2 more }` + - `"mac"` - A click action. + - `"linux"` - - `DoubleClick object { keys, type, x, y }` + - `"ubuntu"` - A double click action. + - `"browser"` - - `Drag object { path, type, keys }` + - `type: "computer_use_preview"` - A drag action. + The type of the computer use tool. Always `computer_use_preview`. - - `Keypress object { keys, type }` + - `"computer_use_preview"` - A collection of keypresses the model would like to perform. + - `WebSearch object { type, filters, search_context_size, user_location }` - - `Move object { type, x, y, keys }` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - A mouse move action. + - `type: "web_search" or "web_search_2025_08_26"` - - `Screenshot object { type }` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - A screenshot action. + - `"web_search"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `"web_search_2025_08_26"` - A scroll action. + - `filters: optional object { allowed_domains }` - - `Type object { text, type }` + Filters for the search. - An action to type in text. + - `allowed_domains: optional array of string` - - `Wait object { type }` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - A wait action. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `agent: optional object { agent_name }` + - `search_context_size: optional "low" or "medium" or "high"` - The agent that produced this 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. - - `agent_name: string` + - `"low"` - The canonical name of the agent that produced this item. + - `"medium"` - - `ComputerCallOutput object { call_id, output, type, 4 more }` + - `"high"` - The output of a computer tool call. + - `user_location: optional object { city, country, region, 2 more }` - - `call_id: string` + The approximate location of the user. - The ID of the computer tool call that produced the output. + - `city: optional string` - - `output: BetaResponseComputerToolCallOutputScreenshot` + Free text input for the city of the user, e.g. `San Francisco`. - A computer screenshot image used with the computer use tool. + - `country: optional string` - - `type: "computer_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 computer screenshot, this property is - always set to `computer_screenshot`. + - `region: optional string` - - `"computer_screenshot"` + Free text input for the region of the user, e.g. `California`. - - `file_id: optional string` + - `timezone: optional string` - The identifier of an uploaded file that contains the screenshot. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `image_url: optional string` + - `type: optional "approximate"` - The URL of the screenshot image. + The type of location approximation. Always `approximate`. - - `type: "computer_call_output"` + - `"approximate"` - The type of the computer tool call output. Always `computer_call_output`. + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `"computer_call_output"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `id: optional string` + - `server_label: string` - The ID of the computer tool call output. + A label for this MCP server, used to identify it in tool calls. - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `type: "mcp"` - The safety checks reported by the API that have been acknowledged by the developer. + The type of the MCP tool. Always `mcp`. - - `id: string` + - `"mcp"` - 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. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `agent: optional object { agent_name }` + List of allowed tool names or a filter object. - The agent that produced this item. + - `McpAllowedTools = array of string` - - `agent_name: string` + A string array of allowed tool names - The canonical name of the agent that produced this item. + - `McpToolFilter object { read_only, tool_names }` - - `status: optional "in_progress" or "completed" or "incomplete"` + A filter object to specify which tools are allowed. - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `read_only: optional boolean` - - `"in_progress"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `"completed"` + - `tool_names: optional array of string` - - `"incomplete"` + List of allowed tool names. - - `WebSearchCall object { id, action, status, 2 more }` + - `authorization: optional string` - The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + 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. - - `id: string` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - The unique ID of the web search 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). - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + Currently supported `connector_id` values are: - 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). + - 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` - - `Search object { type, queries, query, sources }` + - `"connector_dropbox"` - Action type "search" - Performs a web search query. + - `"connector_gmail"` - - `type: "search"` + - `"connector_googlecalendar"` - The action type. + - `"connector_googledrive"` - - `"search"` + - `"connector_microsoftteams"` - - `queries: optional array of string` + - `"connector_outlookcalendar"` - The search queries. + - `"connector_outlookemail"` - - `query: optional string` + - `"connector_sharepoint"` - The search query. + - `defer_loading: optional boolean` - - `sources: optional array of object { type, url }` + Whether this MCP tool is deferred and discovered via tool search. - The sources used in the search. + - `headers: optional map[string]` - - `type: "url"` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The type of source. Always `url`. + - `require_approval: optional object { always, never } or "always" or "never"` - - `"url"` + Specify which of the MCP server's tools require approval. - - `url: string` + - `McpToolApprovalFilter object { always, never }` - The URL of the source. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `OpenPage object { type, url }` + - `always: optional object { read_only, tool_names }` - Action type "open_page" - Opens a specific URL from search results. + A filter object to specify which tools are allowed. - - `type: "open_page"` + - `read_only: optional boolean` - The action 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. - - `"open_page"` + - `tool_names: optional array of string` - - `url: optional string` + List of allowed tool names. - The URL opened by the model. + - `never: optional object { read_only, tool_names }` - - `FindInPage object { pattern, type, url }` + A filter object to specify which tools are allowed. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `read_only: optional boolean` - - `pattern: 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 pattern or text to search for within the page. + - `tool_names: optional array of string` - - `type: "find_in_page"` + List of allowed tool names. - The action type. + - `McpToolApprovalSetting = "always" or "never"` - - `"find_in_page"` + 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. - - `url: string` + - `"always"` - The URL of the page searched for the pattern. + - `"never"` - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `server_description: optional string` - The status of the web search tool call. + Optional description of the MCP server, used to provide more context. - - `"in_progress"` + - `server_url: optional string` - - `"searching"` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `"completed"` + - `tunnel_id: optional string` - - `"failed"` + 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: "web_search_call"` + - `CodeInterpreter object { container, type, allowed_callers }` - The type of the web search tool call. Always `web_search_call`. + A tool that runs Python code to help generate a response to a prompt. - - `"web_search_call"` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `agent: optional object { agent_name }` + 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 agent that produced this item. + - `string` - - `agent_name: string` + The container ID. - The canonical name of the agent that produced this item. + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `FunctionCall object { arguments, call_id, name, 6 more }` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - A tool call to run a function. See the - [function calling guide](/docs/guides/function-calling) for more information. + - `type: "auto"` - - `arguments: string` + Always `auto`. - A JSON string of the arguments to pass to the function. + - `"auto"` - - `call_id: string` + - `file_ids: optional array of string` - The unique ID of the function tool call generated by the model. + An optional list of uploaded files to make available to your code. - - `name: string` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The name of the function to run. + The memory limit for the code interpreter container. - - `type: "function_call"` + - `"1g"` - The type of the function tool call. Always `function_call`. + - `"4g"` - - `"function_call"` + - `"16g"` - - `id: optional string` + - `"64g"` - The unique ID of the function tool call. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `agent: optional object { agent_name }` + Network access policy for the container. - The agent that produced this item. + - `BetaContainerNetworkPolicyDisabled object { type }` - - `agent_name: string` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - The canonical name of the agent that produced this item. + - `type: "code_interpreter"` - - `caller: optional object { type } or object { caller_id, type }` + The type of the code interpreter tool. Always `code_interpreter`. - The execution context that produced this tool call. + - `"code_interpreter"` - - `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` + - `ProgrammaticToolCalling object { type }` - The call ID of the program item that produced this tool call. + - `type: "programmatic_tool_calling"` - - `type: "program"` + The type of the tool. Always `programmatic_tool_calling`. - - `"program"` + - `"programmatic_tool_calling"` - - `namespace: optional string` + - `ImageGeneration object { type, action, background, 9 more }` - The namespace of the function to run. + A tool that generates images using the GPT image models. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `type: "image_generation"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The type of the image generation tool. Always `image_generation`. - - `"in_progress"` + - `"image_generation"` - - `"completed"` + - `action: optional "generate" or "edit" or "auto"` - - `"incomplete"` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `FunctionCallOutput object { call_id, output, type, 4 more }` + - `"generate"` - The output of a function tool call. + - `"edit"` - - `call_id: string` + - `"auto"` - The unique ID of the function tool call generated by the model. + - `background: optional "transparent" or "opaque" or "auto"` - - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - Text, image, or file output of the function tool call. + - `"transparent"` - - `string` + - `"opaque"` - A JSON string of the output of the function tool call. + - `"auto"` - - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` + - `input_fidelity: optional "high" or "low"` - An array of content outputs (text, image, file) for the function tool call. + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + - `"high"` - A text input to the model. + - `"low"` - - `text: string` + - `input_image_mask: optional object { file_id, image_url }` - The text input to the model. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `type: "input_text"` + - `file_id: optional string` - The type of the input item. Always `input_text`. + File ID for the mask image. - - `"input_text"` + - `image_url: optional string` - - `prompt_cache_breakpoint: optional object { mode }` + Base64-encoded mask 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. + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `mode: "explicit"` + The image generation model to use. Default: `gpt-image-1`. - The breakpoint mode. Always `explicit`. + - `string` - - `"explicit"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + The image generation model to use. Default: `gpt-image-1`. - An image input to the model. Learn about [image inputs](/docs/guides/vision) + - `"gpt-image-1"` - - `type: "input_image"` + - `"gpt-image-1-mini"` - The type of the input item. Always `input_image`. + - `"gpt-image-1.5"` - - `"input_image"` + - `moderation: optional "auto" or "low"` - - `detail: optional "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"` - - `file_id: optional string` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The ID of the file to be sent to the model. + - `"png"` - - `image_url: optional string` + - `"webp"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `"jpeg"` - - `prompt_cache_breakpoint: optional object { mode }` + - `partial_images: optional number` - 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. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `mode: "explicit"` + - `quality: optional "low" or "medium" or "high" or "auto"` - The breakpoint mode. Always `explicit`. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `"explicit"` + - `"low"` - - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` + - `"medium"` - A file input to the model. + - `"high"` - - `type: "input_file"` + - `"auto"` - The type of the input item. Always `input_file`. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `"input_file"` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `detail: optional "auto" or "low" or "high"` + - `string` - 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`. + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `"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`. - - `"low"` + - `"1024x1024"` - - `"high"` + - `"1024x1536"` - - `file_data: optional string` + - `"1536x1024"` - The base64-encoded data of the file to be sent to the model. + - `"auto"` - - `file_id: optional string` + - `LocalShell object { type }` - The ID of the file to be sent to the model. + A tool that allows the model to execute shell commands in a local environment. - - `file_url: optional string` + - `type: "local_shell"` - The URL of the file to be sent to the model. + The type of the local shell tool. Always `local_shell`. - - `filename: optional string` + - `"local_shell"` - The name of the file to be sent to the model. + - `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"` - - `type: "function_call_output"` + The tool invocation context(s). - The type of the function tool call output. Always `function_call_output`. + - `"direct"` - - `"function_call_output"` + - `"programmatic"` - - `id: optional string` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - The unique ID of the function tool call output. Populated when this item is returned via API. + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `agent: optional object { agent_name }` + - `BetaLocalEnvironment object { type, skills }` - The agent that produced this item. + - `BetaContainerReference object { container_id, type }` - - `agent_name: string` + - `Custom object { name, type, allowed_callers, 3 more }` - The canonical name of the agent that produced this item. + 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`. - The caller type. Always `direct`. + - `"custom"` + + - `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 tool should be deferred and discovered via tool search. - - `type: "program"` + - `description: optional string` - The caller type. Always `program`. + Optional description of the custom tool, used to provide more context. - - `"program"` + - `format: optional object { type } or object { definition, syntax, type }` - - `status: optional "in_progress" or "completed" or "incomplete"` + The input format for the custom tool. Default is unconstrained text. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `Text object { type }` - - `"in_progress"` + Unconstrained free-form text. - - `"completed"` + - `type: "text"` - - `"incomplete"` + Unconstrained text format. Always `text`. - - `AgentMessage object { author, content, recipient, 3 more }` + - `"text"` - A message routed between agents. + - `Grammar object { definition, syntax, type }` - - `author: string` + A grammar defined by the user. - The sending agent identity. + - `definition: string` - - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` + The grammar definition. - Plaintext, image, or encrypted content sent between agents. + - `syntax: "lark" or "regex"` - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + The syntax of the grammar definition. One of `lark` or `regex`. - A text input to the model. + - `"lark"` - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + - `"regex"` - An image input to the model. Learn about [image inputs](/docs/guides/vision) + - `type: "grammar"` - - `EncryptedContent object { encrypted_content, type }` + Grammar format. Always `grammar`. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `"grammar"` - - `encrypted_content: string` + - `Namespace object { description, name, tools, type }` - Opaque encrypted content. + Groups function/custom tools under a shared namespace. - - `type: "encrypted_content"` + - `description: string` - The type of the input item. Always `encrypted_content`. + A description of the namespace shown to the model. - - `"encrypted_content"` + - `name: string` - - `recipient: string` + The namespace name used in tool calls (for example, `crm`). - The destination agent identity. + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `type: "agent_message"` + The function/custom tools available inside this namespace. - The item type. Always `agent_message`. + - `Function object { name, type, allowed_callers, 5 more }` - - `"agent_message"` + - `name: string` - - `id: optional string` + - `type: "function"` - The unique ID of this agent message item. + - `"function"` - - `agent: optional object { agent_name }` + - `allowed_callers: optional array of "direct" or "programmatic"` - The agent that produced this item. + The tool invocation context(s). - - `agent_name: string` + - `"direct"` - The canonical name of the agent that produced this item. + - `"programmatic"` - - `MultiAgentCall object { action, arguments, call_id, 3 more }` + - `defer_loading: optional boolean` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + Whether this function should be deferred and discovered via tool search. - The multi-agent action that was executed. + - `description: optional string` - - `"spawn_agent"` + - `output_schema: optional map[unknown]` - - `"interrupt_agent"` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `"list_agents"` + - `parameters: optional unknown` - - `"send_message"` + - `strict: optional boolean` - - `"followup_task"` + 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. - - `"wait_agent"` + - `Custom object { name, type, allowed_callers, 3 more }` - - `arguments: string` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - The action arguments as a JSON string. + - `name: string` - - `call_id: string` + The name of the custom tool, used to identify it in tool calls. - The unique ID linking this call to its output. + - `type: "custom"` - - `type: "multi_agent_call"` + The type of the custom tool. Always `custom`. - The item type. Always `multi_agent_call`. + - `"custom"` - - `"multi_agent_call"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `id: optional string` + The tool invocation context(s). - The unique ID of this multi-agent call. + - `"direct"` - - `agent: optional object { agent_name }` + - `"programmatic"` - The agent that produced this item. + - `defer_loading: optional boolean` - - `agent_name: string` + Whether this tool should be deferred and discovered via tool search. - The canonical name of the agent that produced this item. + - `description: optional string` - - `MultiAgentCallOutput object { action, call_id, output, 3 more }` + Optional description of the custom tool, used to provide more context. - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `format: optional object { type } or object { definition, syntax, type }` - The multi-agent action that produced this result. + The input format for the custom tool. Default is unconstrained text. - - `"spawn_agent"` + - `Text object { type }` - - `"interrupt_agent"` + Unconstrained free-form text. - - `"list_agents"` + - `type: "text"` - - `"send_message"` + Unconstrained text format. Always `text`. - - `"followup_task"` + - `"text"` - - `"wait_agent"` + - `Grammar object { definition, syntax, type }` - - `call_id: string` + A grammar defined by the user. - The unique ID of the multi-agent call. + - `definition: string` - - `output: array of object { text, type, annotations }` + The grammar definition. - Text output returned by the multi-agent action. + - `syntax: "lark" or "regex"` - - `text: string` + The syntax of the grammar definition. One of `lark` or `regex`. - The text content. + - `"lark"` - - `type: "output_text"` + - `"regex"` - The content type. Always `output_text`. + - `type: "grammar"` - - `"output_text"` + Grammar format. Always `grammar`. - - `annotations: optional 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 }` + - `"grammar"` - Citations associated with the text content. + - `type: "namespace"` - - `FileCitation object { file_id, filename, index, type }` + The type of the tool. Always `namespace`. - - `file_id: string` + - `"namespace"` - The ID of the file. + - `ToolSearch object { type, description, execution, parameters }` - - `filename: string` + Hosted or BYOT tool search configuration for deferred tools. - The filename of the file cited. + - `type: "tool_search"` - - `index: number` + The type of the tool. Always `tool_search`. - The index of the file in the list of files. + - `"tool_search"` - - `type: "file_citation"` + - `description: optional string` - The citation type. Always `file_citation`. + Description shown to the model for a client-executed tool search tool. - - `"file_citation"` + - `execution: optional "server" or "client"` - - `URLCitation object { end_index, start_index, title, 2 more }` + Whether tool search is executed by the server or by the client. - - `end_index: number` + - `"server"` - The index of the last character of the citation in the message. + - `"client"` - - `start_index: number` + - `parameters: optional unknown` - The index of the first character of the citation in the message. + Parameter schema for a client-executed tool search tool. - - `title: string` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - The title of the cited resource. + 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: "url_citation"` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - The citation type. Always `url_citation`. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `"url_citation"` + - `"web_search_preview"` - - `url: string` + - `"web_search_preview_2025_03_11"` - The URL of the cited resource. + - `search_content_types: optional array of "text" or "image"` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + - `"text"` - - `container_id: string` + - `"image"` - The ID of the container. + - `search_context_size: optional "low" or "medium" or "high"` - - `end_index: number` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - The index of the last character of the citation in the message. + - `"low"` - - `file_id: string` + - `"medium"` - The ID of the container file. + - `"high"` - - `filename: string` + - `user_location: optional object { type, city, country, 2 more }` - The filename of the container file cited. + The user's location. - - `start_index: number` + - `type: "approximate"` - The index of the first character of the citation in the message. + The type of location approximation. Always `approximate`. - - `type: "container_file_citation"` + - `"approximate"` - The citation type. Always `container_file_citation`. + - `city: optional string` - - `"container_file_citation"` + Free text input for the city of the user, e.g. `San Francisco`. - - `type: "multi_agent_call_output"` + - `country: optional string` - The item type. Always `multi_agent_call_output`. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"multi_agent_call_output"` + - `region: optional string` - - `id: optional string` + Free text input for the region of the user, e.g. `California`. - The unique ID of this multi-agent call output. + - `timezone: optional string` - - `agent: optional object { agent_name }` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The agent that produced this item. + - `ApplyPatch object { type, allowed_callers }` - - `agent_name: string` + Allows the assistant to create, delete, or update files using unified diffs. - The canonical name of the agent that produced this item. + - `type: "apply_patch"` - - `ToolSearchCall object { arguments, type, id, 4 more }` + The type of the tool. Always `apply_patch`. - - `arguments: unknown` + - `"apply_patch"` - The arguments supplied to the tool search call. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "tool_search_call"` + The tool invocation context(s). - The item type. Always `tool_search_call`. + - `"direct"` - - `"tool_search_call"` + - `"programmatic"` - - `id: optional string` + - `type: "tool_search_output"` - The unique ID of this tool search call. + The type of the item. Always `tool_search_output`. + + - `"tool_search_output"` - `agent: optional object { agent_name }` @@ -57619,33 +54793,39 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `call_id: optional string` + - `created_by: optional string` - The unique ID of the tool search call generated by the model. + The identifier of the actor that created the item. - - `execution: optional "server" or "client"` + - `AdditionalTools object { id, role, tools, 2 more }` - Whether tool search was executed by the server or by the client. + - `id: string` - - `"server"` + The unique ID of the additional tools item. - - `"client"` + - `role: "unknown" or "user" or "assistant" or 5 more` - - `status: optional "in_progress" or "completed" or "incomplete"` + The role that provided the additional tools. - The status of the tool search call. + - `"unknown"` - - `"in_progress"` + - `"user"` - - `"completed"` + - `"assistant"` - - `"incomplete"` + - `"system"` - - `ToolSearchOutput object { tools, type, id, 4 more }` + - `"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 loaded tool definitions returned by the tool search output. + The additional tool definitions made available at this item. - `Function object { name, parameters, strict, 5 more }` @@ -58166,40 +55346,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `BetaContainerNetworkPolicyDisabled object { type }` - - `type: "disabled"` - - Disable outbound network access. Always `disabled`. - - - `"disabled"` - - `BetaContainerNetworkPolicyAllowlist 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 BetaContainerNetworkPolicyDomainSecret` - - 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`. @@ -58380,128 +55528,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `BetaContainerAuto 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 BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - Network access policy for the container. - - - `BetaContainerNetworkPolicyDisabled object { type }` - - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - - `skills: optional array of BetaSkillReference or BetaInlineSkill` - - An optional list of skills referenced by id or inline data. - - - `BetaSkillReference 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. - - - `BetaInlineSkill object { description, name, source, type }` - - - `description: string` - - The description of the skill. - - - `name: string` - - The name of the skill. - - - `source: BetaInlineSkillSource` - - 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"` - - `BetaLocalEnvironment object { type, skills }` - - `type: "local"` - - Use a local computer environment. - - - `"local"` - - - `skills: optional array of BetaLocalSkill` - - 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. - - `BetaContainerReference 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) @@ -58786,15 +55816,11 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"programmatic"` - - `type: "tool_search_output"` - - The item type. Always `tool_search_output`. - - - `"tool_search_output"` + - `type: "additional_tools"` - - `id: optional string` + The type of the item. Always `additional_tools`. - The unique ID of this tool search output. + - `"additional_tools"` - `agent: optional object { agent_name }` @@ -58804,1077 +55830,923 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `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, 2 more }` - - - `role: "developer"` + - `Compaction object { id, encrypted_content, type, 2 more }` - The role that provided the additional tools. Only `developer` is supported. + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - - `"developer"` + - `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 compaction item. - A list of additional tools made available at this item. + - `encrypted_content: string` - - `Function object { name, parameters, strict, 5 more }` + The encrypted content that was produced by compaction. - 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: "compaction"` - - `name: string` + The type of the item. Always `compaction`. - The name of the function to call. + - `"compaction"` - - `parameters: map[unknown]` + - `agent: optional object { agent_name }` - A JSON schema object describing the parameters of the function. + The agent that produced this item. - - `strict: boolean` + - `agent_name: string` - Whether strict parameter validation is enforced for this function tool. + The canonical name of the agent that produced this item. - - `type: "function"` + - `created_by: optional string` - The type of the function tool. Always `function`. + The identifier of the actor that created the item. - - `"function"` + - `ImageGenerationCall object { id, result, status, 2 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + An image generation request made by the model. - The tool invocation context(s). + - `id: string` - - `"direct"` + The unique ID of the image generation call. - - `"programmatic"` + - `result: string` - - `defer_loading: optional boolean` + The generated image encoded in base64. - Whether this function is deferred and loaded via tool search. + - `status: "in_progress" or "completed" or "generating" or "failed"` - - `description: optional string` + The status of the image generation call. - A description of the function. Used by the model to determine whether or not to call the function. + - `"in_progress"` - - `output_schema: optional map[unknown]` + - `"completed"` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `"generating"` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `"failed"` - 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: "image_generation_call"` - - `type: "file_search"` + The type of the image generation call. Always `image_generation_call`. - The type of the file search tool. Always `file_search`. + - `"image_generation_call"` - - `"file_search"` + - `agent: optional object { agent_name }` - - `vector_store_ids: array of string` + The agent that produced this item. - The IDs of the vector stores to search. + - `agent_name: string` - - `filters: optional object { key, type, value } or object { filters, type }` + The canonical name of the agent that produced this item. - A filter to apply. + - `CodeInterpreterCall object { id, code, container_id, 4 more }` - - `ComparisonFilter object { key, type, value }` + A tool call to run code. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `id: string` - - `key: string` + The unique ID of the code interpreter tool call. - The key to compare against the value. + - `code: string` - - `type: "eq" or "ne" or "gt" or 5 more` + The code to run, or null if not available. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `container_id: string` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + The ID of the container used to run the code. - - `"eq"` + - `outputs: array of object { logs, type } or object { type, url }` - - `"ne"` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `"gt"` + - `Logs object { logs, type }` - - `"gte"` + The logs output from the code interpreter. - - `"lt"` + - `logs: string` - - `"lte"` + The logs output from the code interpreter. - - `"in"` + - `type: "logs"` - - `"nin"` + The type of the output. Always `logs`. - - `value: string or number or boolean or array of string or number` + - `"logs"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `Image object { type, url }` - - `string` + The image output from the code interpreter. - - `number` + - `type: "image"` - - `boolean` + The type of the output. Always `image`. - - `array of string or number` + - `"image"` - - `string` + - `url: string` - - `number` + The URL of the image output from the code interpreter. - - `CompoundFilter object { filters, type }` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - Combine multiple filters using `and` or `or`. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `filters: array of object { key, type, value } or unknown` + - `"in_progress"` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `"completed"` - - `ComparisonFilter object { key, type, value }` + - `"incomplete"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"interpreting"` - - `key: string` + - `"failed"` - The key to compare against the value. + - `type: "code_interpreter_call"` - - `type: "eq" or "ne" or "gt" or 5 more` + The type of the code interpreter tool call. Always `code_interpreter_call`. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"code_interpreter_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 + - `agent: optional object { agent_name }` - - `"eq"` + The agent that produced this item. - - `"ne"` + - `agent_name: string` - - `"gt"` + The canonical name of the agent that produced this item. - - `"gte"` + - `LocalShellCall object { id, action, call_id, 3 more }` - - `"lt"` + A tool call to run a command on the local shell. - - `"lte"` + - `id: string` - - `"in"` + The unique ID of the local shell call. - - `"nin"` + - `action: object { command, env, type, 3 more }` - - `value: string or number or boolean or array of string or number` + Execute a shell command on the server. - The value to compare against the attribute key; supports string, number, or boolean types. + - `command: array of string` - - `string` + The command to run. - - `number` + - `env: map[string]` - - `boolean` + Environment variables to set for the command. - - `array of string or number` + - `type: "exec"` - - `string` + The type of the local shell action. Always `exec`. - - `number` + - `"exec"` - - `unknown` + - `timeout_ms: optional number` - - `type: "and" or "or"` + Optional timeout in milliseconds for the command. - Type of operation: `and` or `or`. + - `user: optional string` - - `"and"` + Optional user to run the command as. - - `"or"` + - `working_directory: optional string` - - `max_num_results: optional number` + Optional working directory to run the command in. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `call_id: string` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + The unique ID of the local shell tool call generated by the model. - Ranking options for search. + - `status: "in_progress" or "completed" or "incomplete"` - - `hybrid_search: optional object { embedding_weight, text_weight }` + The status of the local shell call. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `"in_progress"` - - `embedding_weight: number` + - `"completed"` - The weight of the embedding in the reciprocal ranking fusion. + - `"incomplete"` - - `text_weight: number` + - `type: "local_shell_call"` - The weight of the text in the reciprocal ranking fusion. + The type of the local shell call. Always `local_shell_call`. - - `ranker: optional "auto" or "default-2024-11-15"` + - `"local_shell_call"` - The ranker to use for the file search. + - `agent: optional object { agent_name }` - - `"auto"` + The agent that produced this item. - - `"default-2024-11-15"` + - `agent_name: string` - - `score_threshold: optional number` + The canonical name of the agent that produced this item. - 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. + - `LocalShellCallOutput object { id, output, type, 2 more }` - - `Computer object { type }` + The output of a local shell tool call. - 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 unique ID of the local shell tool call generated by the model. - The type of the computer tool. Always `computer`. + - `output: string` - - `"computer"` + A JSON string of the output of the local shell tool call. - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `type: "local_shell_call_output"` - 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 local shell tool call output. Always `local_shell_call_output`. - - `display_height: number` + - `"local_shell_call_output"` - The height of the computer display. + - `agent: optional object { agent_name }` - - `display_width: number` + The agent that produced this item. - The width of the computer display. + - `agent_name: string` - - `environment: "windows" or "mac" or "linux" or 2 more` + The canonical name of the agent that produced this item. - The type of computer environment to control. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"windows"` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `"mac"` + - `"in_progress"` - - `"linux"` + - `"completed"` - - `"ubuntu"` + - `"incomplete"` - - `"browser"` + - `ShellCall object { id, action, call_id, 6 more }` - - `type: "computer_use_preview"` + A tool call that executes one or more shell commands in a managed environment. - The type of the computer use tool. Always `computer_use_preview`. + - `id: string` - - `"computer_use_preview"` + The unique ID of the shell tool call. Populated when this item is returned via API. - - `WebSearch object { type, filters, search_context_size, user_location }` + - `action: object { commands, max_output_length, timeout_ms }` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + The shell commands and limits that describe how to run the tool call. - - `type: "web_search" or "web_search_2025_08_26"` + - `commands: array of string` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `max_output_length: number` - - `"web_search"` + Optional maximum number of characters to return from each command. - - `"web_search_2025_08_26"` + - `timeout_ms: number` - - `filters: optional object { allowed_domains }` + Optional timeout in milliseconds for the commands. - Filters for the search. + - `call_id: string` - - `allowed_domains: optional array of string` + The unique ID of the shell tool call generated by the model. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + Represents the use of a local environment to perform shell actions. - - `search_context_size: optional "low" or "medium" or "high"` + - `BetaResponseLocalEnvironment object { 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. + Represents the use of a local environment to perform shell actions. - - `"low"` + - `type: "local"` - - `"medium"` + The environment type. Always `local`. - - `"high"` + - `"local"` - - `user_location: optional object { city, country, region, 2 more }` + - `BetaResponseContainerReference object { container_id, type }` - The approximate location of the user. + Represents a container created with /v1/containers. - - `city: optional string` + - `container_id: string` - Free text input for the city of the user, e.g. `San Francisco`. + - `type: "container_reference"` - - `country: optional string` + The environment type. Always `container_reference`. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `"container_reference"` - - `region: optional string` + - `status: "in_progress" or "completed" or "incomplete"` - Free text input for the region of the user, e.g. `California`. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `timezone: optional string` + - `"in_progress"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"completed"` - - `type: optional "approximate"` + - `"incomplete"` - The type of location approximation. Always `approximate`. + - `type: "shell_call"` - - `"approximate"` + The type of the item. Always `shell_call`. - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `"shell_call"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + - `agent: optional object { agent_name }` - - `server_label: string` + The agent that produced this item. - A label for this MCP server, used to identify it in tool calls. + - `agent_name: string` - - `type: "mcp"` + The canonical name of the agent that produced this item. - The type of the MCP tool. Always `mcp`. + - `caller: optional object { type } or object { caller_id, type }` - - `"mcp"` + The execution context that produced this tool call. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `Direct object { type }` - The tool invocation context(s). + - `type: "direct"` - `"direct"` - - `"programmatic"` - - - `allowed_tools: optional array of string or object { read_only, tool_names }` - - List of allowed tool names or a filter object. - - - `McpAllowedTools = array of string` - - A string array of allowed tool names - - - `McpToolFilter object { read_only, tool_names }` - - A filter object to specify which tools are allowed. - - - `read_only: optional boolean` - - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. - - - `tool_names: optional array of string` - - List of allowed tool names. - - - `authorization: optional string` - - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. - - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - Identifier for service connectors, like those available in ChatGPT. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more - about service connectors [here](/docs/guides/tools-remote-mcp#connectors). - - Currently supported `connector_id` values are: - - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` - - - `"connector_dropbox"` - - - `"connector_gmail"` - - - `"connector_googlecalendar"` - - - `"connector_googledrive"` - - - `"connector_microsoftteams"` - - - `"connector_outlookcalendar"` - - - `"connector_outlookemail"` - - - `"connector_sharepoint"` - - - `defer_loading: optional boolean` - - Whether this MCP tool is deferred and discovered via tool search. - - - `headers: optional map[string]` - - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. - - - `require_approval: optional object { always, never } or "always" or "never"` - - Specify which of the MCP server's tools require approval. - - - `McpToolApprovalFilter object { always, never }` - - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. - - - `always: optional object { read_only, tool_names }` - - A filter object to specify which tools are allowed. - - - `read_only: optional boolean` - - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. - - - `tool_names: optional array of string` - - List of allowed tool names. - - - `never: optional object { read_only, tool_names }` + - `Program object { caller_id, type }` - A filter object to specify which tools are allowed. + - `caller_id: string` - - `read_only: optional boolean` + The call ID of the program item 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. + - `type: "program"` - - `tool_names: optional array of string` + - `"program"` - List of allowed tool names. + - `created_by: optional string` - - `McpToolApprovalSetting = "always" or "never"` + The ID of the entity that created this tool call. - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` - - `"always"` + The output of a shell tool call that was emitted. - - `"never"` + - `id: string` - - `server_description: optional string` + The unique ID of the shell call output. Populated when this item is returned via API. - Optional description of the MCP server, used to provide more context. + - `call_id: string` - - `server_url: optional string` + The unique ID of the shell tool call generated by the model. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `max_output_length: number` - - `tunnel_id: optional string` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + - `output: array of object { outcome, stderr, stdout, created_by }` - - `CodeInterpreter object { container, type, allowed_callers }` + An array of shell call output contents - A tool that runs Python code to help generate a response to a prompt. + - `outcome: object { type } or object { exit_code, type }` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - 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. + - `Timeout object { type }` - - `string` + Indicates that the shell call exceeded its configured time limit. - The container ID. + - `type: "timeout"` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + The outcome type. Always `timeout`. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `"timeout"` - - `type: "auto"` + - `Exit object { exit_code, type }` - Always `auto`. + Indicates that the shell commands finished and returned an exit code. - - `"auto"` + - `exit_code: number` - - `file_ids: optional array of string` + Exit code from the shell process. - An optional list of uploaded files to make available to your code. + - `type: "exit"` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + The outcome type. Always `exit`. - The memory limit for the code interpreter container. + - `"exit"` - - `"1g"` + - `stderr: string` - - `"4g"` + The standard error output that was captured. - - `"16g"` + - `stdout: string` - - `"64g"` + The standard output that was captured. - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `created_by: optional string` - Network access policy for the container. + The identifier of the actor that created the item. - - `BetaContainerNetworkPolicyDisabled object { type }` + - `status: "in_progress" or "completed" or "incomplete"` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `type: "code_interpreter"` + - `"in_progress"` - The type of the code interpreter tool. Always `code_interpreter`. + - `"completed"` - - `"code_interpreter"` + - `"incomplete"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "shell_call_output"` - The tool invocation context(s). + The type of the shell call output. Always `shell_call_output`. - - `"direct"` + - `"shell_call_output"` - - `"programmatic"` + - `agent: optional object { agent_name }` - - `ProgrammaticToolCalling object { type }` + The agent that produced this item. - - `type: "programmatic_tool_calling"` + - `agent_name: string` - The type of the tool. Always `programmatic_tool_calling`. + The canonical name of the agent that produced this item. - - `"programmatic_tool_calling"` + - `caller: optional object { type } or object { caller_id, type }` - - `ImageGeneration object { type, action, background, 9 more }` + The execution context that produced this tool call. - A tool that generates images using the GPT image models. + - `Direct object { type }` - - `type: "image_generation"` + - `type: "direct"` - The type of the image generation tool. Always `image_generation`. + - `"direct"` - - `"image_generation"` + - `Program object { caller_id, type }` - - `action: optional "generate" or "edit" or "auto"` + - `caller_id: string` - Whether to generate a new image or edit an existing image. Default: `auto`. + The call ID of the program item that produced this tool call. - - `"generate"` + - `type: "program"` - - `"edit"` + - `"program"` - - `"auto"` + - `created_by: optional string` - - `background: optional "transparent" or "opaque" or "auto"` + The identifier of the actor that created the item. - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + - `ApplyPatchCall object { id, call_id, operation, 5 more }` - - `"transparent"` + A tool call that applies file diffs by creating, deleting, or updating files. - - `"opaque"` + - `id: string` - - `"auto"` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `input_fidelity: optional "high" or "low"` + - `call_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 apply patch tool call generated by the model. - - `"high"` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - `"low"` + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `input_image_mask: optional object { file_id, image_url }` + - `CreateFile object { diff, path, type }` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + Instruction describing how to create a file via the apply_patch tool. - - `file_id: optional string` + - `diff: string` - File ID for the mask image. + Diff to apply. - - `image_url: optional string` + - `path: string` - Base64-encoded mask image. + Path of the file to create. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `type: "create_file"` - The image generation model to use. Default: `gpt-image-1`. + Create a new file with the provided diff. - - `string` + - `"create_file"` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `DeleteFile object { path, type }` - The image generation model to use. Default: `gpt-image-1`. + Instruction describing how to delete a file via the apply_patch tool. - - `"gpt-image-1"` + - `path: string` - - `"gpt-image-1-mini"` + Path of the file to delete. - - `"gpt-image-1.5"` + - `type: "delete_file"` - - `moderation: optional "auto" or "low"` + Delete the specified file. - Moderation level for the generated image. Default: `auto`. + - `"delete_file"` - - `"auto"` + - `UpdateFile object { diff, path, type }` - - `"low"` + Instruction describing how to update a file via the apply_patch tool. - - `output_compression: optional number` + - `diff: string` - Compression level for the output image. Default: 100. + Diff to apply. - - `output_format: optional "png" or "webp" or "jpeg"` + - `path: string` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + Path of the file to update. - - `"png"` + - `type: "update_file"` - - `"webp"` + Update an existing file with the provided diff. - - `"jpeg"` + - `"update_file"` - - `partial_images: optional number` + - `status: "in_progress" or "completed"` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `"in_progress"` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `"completed"` - - `"low"` + - `type: "apply_patch_call"` - - `"medium"` + The type of the item. Always `apply_patch_call`. - - `"high"` + - `"apply_patch_call"` - - `"auto"` + - `agent: optional object { agent_name }` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The agent that produced this item. - 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`. + - `agent_name: string` - - `string` + The canonical name of the agent that produced this item. - - `"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, 5 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 BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `"completed"` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `"failed"` - - `BetaLocalEnvironment object { type, skills }` + - `type: "apply_patch_call_output"` - - `BetaContainerReference 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) + - `agent: optional object { agent_name }` - - `name: string` + The agent that produced this item. - The name of the custom tool, used to identify it in tool calls. + - `agent_name: string` - - `type: "custom"` + The canonical name of the agent that produced this item. - The type of the custom tool. Always `custom`. + - `caller: optional object { type } or object { caller_id, type }` - - `"custom"` + The execution context that produced this tool call. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `Direct object { type }` - The tool invocation context(s). + - `type: "direct"` - `"direct"` - - `"programmatic"` + - `Program object { caller_id, type }` - - `defer_loading: optional boolean` + - `caller_id: string` - Whether this tool should be deferred and discovered via tool search. + The call ID of the program item that produced this tool call. - - `description: optional string` + - `type: "program"` - Optional description of the custom tool, used to provide more context. + - `"program"` - - `format: optional object { type } or object { definition, syntax, type }` + - `created_by: optional string` - The input format for the custom tool. Default is unconstrained text. + The ID of the entity that created this tool call output. - - `Text object { type }` + - `output: optional string` - Unconstrained free-form text. + Optional textual output returned by the apply patch tool. - - `type: "text"` + - `McpCall object { id, arguments, name, 7 more }` - Unconstrained text format. Always `text`. + An invocation of a tool on an MCP server. - - `"text"` + - `id: string` - - `Grammar object { definition, syntax, type }` + The unique ID of the tool call. - A grammar defined by the user. + - `arguments: string` - - `definition: string` + A JSON string of the arguments passed to the tool. - The grammar definition. + - `name: string` - - `syntax: "lark" or "regex"` + The name of the tool that was run. - The syntax of the grammar definition. One of `lark` or `regex`. + - `server_label: string` - - `"lark"` + The label of the MCP server running the tool. - - `"regex"` + - `type: "mcp_call"` - - `type: "grammar"` + The type of the item. Always `mcp_call`. - Grammar format. Always `grammar`. + - `"mcp_call"` - - `"grammar"` + - `agent: optional object { agent_name }` - - `Namespace object { description, name, tools, type }` + The agent that produced this item. - Groups function/custom tools under a shared namespace. + - `agent_name: string` - - `description: string` + The canonical name of the agent that produced this item. - A description of the namespace shown to the model. + - `approval_request_id: optional string` - - `name: 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 namespace name used in tool calls (for example, `crm`). + - `error: optional string` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + The error from the tool call, if any. - The function/custom tools available inside this namespace. + - `output: optional string` - - `Function object { name, type, allowed_callers, 5 more }` + The output from the tool call. - - `name: string` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `type: "function"` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `"function"` + - `"in_progress"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"completed"` - The tool invocation context(s). + - `"incomplete"` - - `"direct"` + - `"calling"` - - `"programmatic"` + - `"failed"` - - `defer_loading: optional boolean` + - `McpListTools object { id, server_label, tools, 3 more }` - Whether this function should be deferred and discovered via tool search. + A list of tools available on an MCP server. - - `description: optional string` + - `id: string` - - `output_schema: optional map[unknown]` + The unique ID of the list. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `server_label: string` - - `parameters: optional unknown` + The label of the MCP server. - - `strict: optional boolean` + - `tools: array of object { input_schema, name, annotations, description }` - 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 tools available on the server. - - `Custom object { name, type, allowed_callers, 3 more }` + - `input_schema: unknown` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + The JSON schema describing the tool's input. - `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"` + The name of the tool. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `annotations: optional unknown` - The tool invocation context(s). + Additional annotations about the tool. - - `"direct"` + - `description: optional string` - - `"programmatic"` + The description of the tool. - - `defer_loading: optional boolean` + - `type: "mcp_list_tools"` - Whether this tool should be deferred and discovered via tool search. + The type of the item. Always `mcp_list_tools`. - - `description: optional string` + - `"mcp_list_tools"` - Optional description of the custom tool, used to provide more context. + - `agent: optional object { agent_name }` - - `format: optional object { type } or object { definition, syntax, type }` + The agent that produced this item. - The input format for the custom tool. Default is unconstrained text. + - `agent_name: string` - - `Text object { type }` + The canonical name of the agent that produced this item. - Unconstrained free-form text. + - `error: optional string` - - `type: "text"` + Error message if the server could not list tools. - Unconstrained text format. Always `text`. + - `McpApprovalRequest object { id, arguments, name, 3 more }` - - `"text"` + A request for human approval of a tool invocation. - - `Grammar object { definition, syntax, type }` + - `id: string` - A grammar defined by the user. + The unique ID of the approval request. - - `definition: string` + - `arguments: string` - The grammar definition. + A JSON string of arguments for the tool. - - `syntax: "lark" or "regex"` + - `name: string` - The syntax of the grammar definition. One of `lark` or `regex`. + The name of the tool to run. - - `"lark"` + - `server_label: string` - - `"regex"` + The label of the MCP server making the request. - - `type: "grammar"` + - `type: "mcp_approval_request"` - Grammar format. Always `grammar`. + The type of the item. Always `mcp_approval_request`. - - `"grammar"` + - `"mcp_approval_request"` - - `type: "namespace"` + - `agent: optional object { agent_name }` - The type of the tool. Always `namespace`. + The agent that produced this item. - - `"namespace"` + - `agent_name: string` - - `ToolSearch object { type, description, execution, parameters }` + The canonical name of the agent that produced this item. - Hosted or BYOT tool search configuration for deferred tools. + - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` - - `type: "tool_search"` + A response to an MCP approval request. - The type of the tool. Always `tool_search`. + - `id: string` - - `"tool_search"` + The unique ID of the approval response - - `description: optional string` + - `approval_request_id: string` - Description shown to the model for a client-executed tool search tool. + The ID of the approval request being answered. - - `execution: optional "server" or "client"` + - `approve: boolean` - Whether tool search is executed by the server or by the client. + Whether the request was approved. - - `"server"` + - `type: "mcp_approval_response"` - - `"client"` + The type of the item. Always `mcp_approval_response`. - - `parameters: optional unknown` + - `"mcp_approval_response"` - Parameter schema for a client-executed tool search tool. + - `agent: optional object { agent_name }` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + The agent that produced this item. - 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). + - `agent_name: string` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + The canonical name of the agent that produced this item. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `reason: optional string` - - `"web_search_preview"` + Optional reason for the decision. - - `"web_search_preview_2025_03_11"` + - `CustomToolCall object { call_id, input, name, 5 more }` - - `search_content_types: optional array of "text" or "image"` + A call to a custom tool created by the model. - - `"text"` + - `call_id: string` - - `"image"` + An identifier used to map this custom tool call to a tool call output. - - `search_context_size: optional "low" or "medium" or "high"` + - `input: 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 input for the custom tool call generated by the model. - - `"low"` + - `name: string` - - `"medium"` + The name of the custom tool being called. - - `"high"` + - `type: "custom_tool_call"` - - `user_location: optional object { type, city, country, 2 more }` + The type of the custom tool call. Always `custom_tool_call`. - The user's location. + - `"custom_tool_call"` - - `type: "approximate"` + - `id: optional string` - The type of location approximation. Always `approximate`. + The unique ID of the custom tool call in the OpenAI platform. - - `"approximate"` + - `agent: optional object { agent_name }` - - `city: optional string` + The agent that produced this item. - Free text input for the city of the user, e.g. `San Francisco`. + - `agent_name: string` - - `country: optional string` + The canonical name of the agent that produced this item. - 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"` + - `namespace: optional string` - The tool invocation context(s). + The namespace of the custom tool being called. - - `"direct"` + - `CustomToolCallOutput object { id, call_id, output, 5 more }` - - `"programmatic"` + - `id: string` - - `type: "additional_tools"` + The unique ID of the custom tool call output item. - The item type. Always `additional_tools`. + - `call_id: string` - - `"additional_tools"` + The call ID, used to map this custom tool call output to a custom tool call. - - `id: optional string` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The unique ID of this additional tools item. + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `agent: optional object { agent_name }` + - `StringOutput = string` - The agent that produced this item. + A string of the output of the custom tool call. - - `agent_name: string` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The canonical name of the agent that produced this item. + Text, image, or file output of the custom tool call. - - `Reasoning object { id, summary, type, 4 more }` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - 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). + A text input to the model. - - `id: string` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - The unique identifier of the reasoning content. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `summary: array of object { text, type }` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - Reasoning summary content. + A file input to the model. - - `text: string` + - `status: "in_progress" or "completed" or "incomplete"` - A summary of the reasoning output from the model so far. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `type: "summary_text"` + - `"in_progress"` - The type of the object. Always `summary_text`. + - `"completed"` - - `"summary_text"` + - `"incomplete"` - - `type: "reasoning"` + - `type: "custom_tool_call_output"` - The type of the object. Always `reasoning`. + The type of the custom tool call output. Always `custom_tool_call_output`. - - `"reasoning"` + - `"custom_tool_call_output"` - `agent: optional object { agent_name }` @@ -59884,2076 +56756,2440 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `content: optional array of object { text, type }` + - `caller: optional object { type } or object { caller_id, type }` - Reasoning text content. + The execution context that produced this tool call. - - `text: string` + - `Direct object { type }` - The reasoning text from the model. + - `type: "direct"` - - `type: "reasoning_text"` + The caller type. Always `direct`. - The type of the reasoning text. Always `reasoning_text`. + - `"direct"` - - `"reasoning_text"` + - `Program object { caller_id, type }` - - `encrypted_content: optional string` + - `caller_id: 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 call ID of the program item that produced this tool call. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `type: "program"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The caller type. Always `program`. - - `"in_progress"` + - `"program"` - - `"completed"` + - `created_by: optional string` - - `"incomplete"` + The identifier of the actor that created the item. - - `Compaction object { encrypted_content, type, id, agent }` + - `parallel_tool_calls: boolean` - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + Whether to allow the model to run tool calls in parallel. - - `encrypted_content: string` + - `temperature: number` - The encrypted content of the compaction summary. + 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. - - `type: "compaction"` + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - The type of the item. Always `compaction`. + 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. - - `"compaction"` + - `BetaToolChoiceOptions = "none" or "auto" or "required"` - - `id: optional string` + Controls which (if any) tool is called by the model. - The ID of the compaction item. + `none` means the model will not call any tool and instead generates a message. - - `agent: optional object { agent_name }` + `auto` means the model can pick between generating a message or calling one or + more tools. - The agent that produced this item. + `required` means the model must call one or more tools. - - `agent_name: string` + - `"none"` - The canonical name of the agent that produced this item. + - `"auto"` - - `ImageGenerationCall object { id, result, status, 2 more }` + - `"required"` - An image generation request made by the model. + - `BetaToolChoiceAllowed object { mode, tools, type }` - - `id: string` + Constrains the tools available to the model to a pre-defined set. - The unique ID of the image generation call. + - `mode: "auto" or "required"` - - `result: string` + Constrains the tools available to the model to a pre-defined set. - The generated image encoded in base64. + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `status: "in_progress" or "completed" or "generating" or "failed"` + `required` requires the model to call one or more of the allowed tools. - The status of the image generation call. + - `"auto"` - - `"in_progress"` + - `"required"` - - `"completed"` + - `tools: array of map[unknown]` - - `"generating"` + A list of tool definitions that the model should be allowed to call. - - `"failed"` + For the Responses API, the list of tool definitions might look like: - - `type: "image_generation_call"` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - The type of the image generation call. Always `image_generation_call`. + - `type: "allowed_tools"` - - `"image_generation_call"` + Allowed tool configuration type. Always `allowed_tools`. - - `agent: optional object { agent_name }` + - `"allowed_tools"` - The agent that produced this item. + - `BetaToolChoiceTypes object { type }` - - `agent_name: string` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](/docs/guides/tools). - The canonical name of the agent that produced this item. + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` - - `CodeInterpreterCall object { id, code, container_id, 4 more }` + The type of hosted tool the model should to use. Learn more about + [built-in tools](/docs/guides/tools). - A tool call to run code. + Allowed values are: - - `id: string` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - The unique ID of the code interpreter tool call. + - `"file_search"` - - `code: string` + - `"web_search_preview"` - The code to run, or null if not available. + - `"computer"` - - `container_id: string` + - `"computer_use_preview"` - The ID of the container used to run the code. + - `"computer_use"` - - `outputs: array of object { logs, type } or object { type, url }` + - `"web_search_preview_2025_03_11"` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `"image_generation"` - - `Logs object { logs, type }` + - `"code_interpreter"` - The logs output from the code interpreter. + - `BetaToolChoiceFunction object { name, type }` - - `logs: string` + Use this option to force the model to call a specific function. - The logs output from the code interpreter. + - `name: string` - - `type: "logs"` + The name of the function to call. - The type of the output. Always `logs`. + - `type: "function"` - - `"logs"` + For function calling, the type is always `function`. - - `Image object { type, url }` + - `"function"` - The image output from the code interpreter. + - `BetaToolChoiceMcp object { server_label, type, name }` - - `type: "image"` + Use this option to force the model to call a specific tool on a remote MCP server. - The type of the output. Always `image`. + - `server_label: string` - - `"image"` + The label of the MCP server to use. - - `url: string` + - `type: "mcp"` - The URL of the image output from the code interpreter. + For MCP tools, the type is always `mcp`. - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `"mcp"` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `name: optional string` - - `"in_progress"` + The name of the tool to call on the server. - - `"completed"` + - `BetaToolChoiceCustom object { name, type }` - - `"incomplete"` + Use this option to force the model to call a specific custom tool. - - `"interpreting"` + - `name: string` - - `"failed"` + The name of the custom tool to call. - - `type: "code_interpreter_call"` + - `type: "custom"` - The type of the code interpreter tool call. Always `code_interpreter_call`. + For custom tool calling, the type is always `custom`. - - `"code_interpreter_call"` + - `"custom"` - - `agent: optional object { agent_name }` + - `BetaSpecificProgrammaticToolCallingParam object { type }` - The agent that produced this item. + - `type: "programmatic_tool_calling"` - - `agent_name: string` + The tool to call. Always `programmatic_tool_calling`. - The canonical name of the agent that produced this item. + - `"programmatic_tool_calling"` - - `LocalShellCall object { id, action, call_id, 3 more }` + - `BetaToolChoiceApplyPatch object { type }` - A tool call to run a command on the local shell. + Forces the model to call the apply_patch tool when executing a tool call. - - `id: string` + - `type: "apply_patch"` - The unique ID of the local shell call. + The tool to call. Always `apply_patch`. - - `action: object { command, env, type, 3 more }` + - `"apply_patch"` - Execute a shell command on the server. + - `BetaToolChoiceShell object { type }` - - `command: array of string` + Forces the model to call the shell tool when a tool call is required. - The command to run. + - `type: "shell"` - - `env: map[string]` + The tool to call. Always `shell`. - Environment variables to set for the command. + - `"shell"` - - `type: "exec"` + - `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 type of the local shell action. Always `exec`. + 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. - - `"exec"` + We support the following categories of tools: - - `timeout_ms: optional number` + - **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. - Optional timeout in milliseconds for the command. + - `Function object { name, parameters, strict, 5 more }` - - `user: optional 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). - Optional user to run the command as. + - `name: string` - - `working_directory: optional string` + The name of the function to call. - Optional working directory to run the command in. + - `parameters: map[unknown]` - - `call_id: string` + A JSON schema object describing the parameters of the function. - The unique ID of the local shell tool call generated by the model. + - `strict: boolean` - - `status: "in_progress" or "completed" or "incomplete"` + Whether strict parameter validation is enforced for this function tool. - The status of the local shell call. + - `type: "function"` - - `"in_progress"` + The type of the function tool. Always `function`. - - `"completed"` + - `"function"` - - `"incomplete"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "local_shell_call"` + The tool invocation context(s). - The type of the local shell call. Always `local_shell_call`. + - `"direct"` - - `"local_shell_call"` + - `"programmatic"` - - `agent: optional object { agent_name }` + - `defer_loading: optional boolean` - The agent that produced this item. + Whether this function is deferred and loaded via tool search. - - `agent_name: string` + - `description: optional string` - The canonical name of the agent that produced this item. + A description of the function. Used by the model to determine whether or not to call the function. - - `LocalShellCallOutput object { id, output, type, 2 more }` + - `output_schema: optional map[unknown]` - The output of a local shell tool call. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `id: string` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - The unique ID of the local shell tool call generated by the model. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `output: string` + - `type: "file_search"` - A JSON string of the output of the local shell tool call. + The type of the file search tool. Always `file_search`. - - `type: "local_shell_call_output"` + - `"file_search"` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `vector_store_ids: array of string` - - `"local_shell_call_output"` + The IDs of the vector stores to search. - - `agent: optional object { agent_name }` + - `filters: optional object { key, type, value } or object { filters, type }` - The agent that produced this item. + A filter to apply. - - `agent_name: string` + - `ComparisonFilter object { key, type, value }` - The canonical name of the agent that produced this item. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `key: string` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The key to compare against the value. - - `"in_progress"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `"completed"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"incomplete"` + - `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 - - `ShellCall object { action, call_id, type, 5 more }` + - `"eq"` - A tool representing a request to execute one or more shell commands. + - `"ne"` - - `action: object { commands, max_output_length, timeout_ms }` + - `"gt"` - The shell commands and limits that describe how to run the tool call. + - `"gte"` - - `commands: array of string` + - `"lt"` - Ordered shell commands for the execution environment to run. + - `"lte"` - - `max_output_length: optional number` + - `"in"` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `"nin"` - - `timeout_ms: optional number` + - `value: string or number or boolean or array of string or number` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + The value to compare against the attribute key; supports string, number, or boolean types. - - `call_id: string` + - `string` - The unique ID of the shell tool call generated by the model. + - `number` - - `type: "shell_call"` + - `boolean` - The type of the item. Always `shell_call`. + - `array of string or number` - - `"shell_call"` + - `string` - - `id: optional string` + - `number` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `CompoundFilter object { filters, type }` - - `agent: optional object { agent_name }` + Combine multiple filters using `and` or `or`. - The agent that produced this item. + - `filters: array of object { key, type, value } or unknown` - - `agent_name: string` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The canonical name of the agent that produced this item. + - `ComparisonFilter object { key, type, value }` - - `caller: optional object { type } or object { caller_id, type }` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The execution context that produced this tool call. + - `key: string` - - `Direct object { type }` + The key to compare against the value. - - `type: "direct"` + - `type: "eq" or "ne" or "gt" or 5 more` - The caller type. Always `direct`. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"direct"` + - `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 - - `Program object { caller_id, type }` + - `"eq"` - - `caller_id: string` + - `"ne"` - The call ID of the program item that produced this tool call. + - `"gt"` - - `type: "program"` + - `"gte"` - The caller type. Always `program`. + - `"lt"` - - `"program"` + - `"lte"` - - `environment: optional BetaLocalEnvironment or BetaContainerReference` + - `"in"` - The environment to execute the shell commands in. + - `"nin"` - - `BetaLocalEnvironment object { type, skills }` + - `value: string or number or boolean or array of string or number` - - `BetaContainerReference object { container_id, type }` + The value to compare against the attribute key; supports string, number, or boolean types. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `string` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `number` - - `"in_progress"` + - `boolean` - - `"completed"` + - `array of string or number` - - `"incomplete"` + - `string` - - `ShellCallOutput object { call_id, output, type, 5 more }` + - `number` - The streamed output items emitted by a shell tool call. + - `unknown` - - `call_id: string` + - `type: "and" or "or"` - The unique ID of the shell tool call generated by the model. + Type of operation: `and` or `or`. - - `output: array of BetaResponseFunctionShellCallOutputContent` + - `"and"` + + - `"or"` + + - `max_num_results: optional number` + + The maximum number of results to return. This number should be between 1 and 50 inclusive. + + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + + Ranking options for search. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `embedding_weight: number` - - `outcome: object { type } or object { exit_code, type }` + The weight of the embedding in the reciprocal ranking fusion. - The exit or timeout outcome associated with this shell call. + - `text_weight: number` - - `Timeout object { type }` + The weight of the text in the reciprocal ranking fusion. - Indicates that the shell call exceeded its configured time limit. + - `ranker: optional "auto" or "default-2024-11-15"` - - `type: "timeout"` + The ranker to use for the file search. - The outcome type. Always `timeout`. + - `"auto"` - - `"timeout"` + - `"default-2024-11-15"` - - `Exit object { exit_code, type }` + - `score_threshold: optional number` - Indicates that the shell commands finished and returned an exit 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. - - `exit_code: number` + - `Computer object { type }` - The exit code returned by the shell process. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `type: "exit"` + - `type: "computer"` - The outcome type. Always `exit`. + The type of the computer tool. Always `computer`. - - `"exit"` + - `"computer"` - - `stderr: string` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - Captured stderr output for the shell call. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `stdout: string` + - `display_height: number` - Captured stdout output for the shell call. + The height of the computer display. - - `type: "shell_call_output"` + - `display_width: number` - The type of the item. Always `shell_call_output`. + The width of the computer display. - - `"shell_call_output"` + - `environment: "windows" or "mac" or "linux" or 2 more` - - `id: optional string` + The type of computer environment to control. - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `"windows"` - - `agent: optional object { agent_name }` + - `"mac"` - The agent that produced this item. + - `"linux"` - - `agent_name: string` + - `"ubuntu"` - The canonical name of the agent that produced this item. + - `"browser"` - - `caller: optional object { type } or object { caller_id, type }` + - `type: "computer_use_preview"` - The execution context that produced this tool call. + The type of the computer use tool. Always `computer_use_preview`. - - `Direct object { type }` + - `"computer_use_preview"` - - `type: "direct"` + - `WebSearch object { type, filters, search_context_size, user_location }` - The caller type. Always `direct`. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `"direct"` + - `type: "web_search" or "web_search_2025_08_26"` - - `Program object { caller_id, type }` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `caller_id: string` + - `"web_search"` - The call ID of the program item that produced this tool call. + - `"web_search_2025_08_26"` - - `type: "program"` + - `filters: optional object { allowed_domains }` - The caller type. Always `program`. + Filters for the search. - - `"program"` + - `allowed_domains: optional array of string` - - `max_output_length: optional number` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - The maximum number of UTF-8 characters captured for this shell call's combined output. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `search_context_size: optional "low" or "medium" or "high"` - The status of the shell call 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. - - `"in_progress"` + - `"low"` - - `"completed"` + - `"medium"` - - `"incomplete"` + - `"high"` - - `ApplyPatchCall object { call_id, operation, status, 4 more }` + - `user_location: optional object { city, country, region, 2 more }` - A tool call representing a request to create, delete, or update files using diff patches. + The approximate location of the user. - - `call_id: string` + - `city: optional string` - The unique ID of the apply patch tool call generated by the model. + Free text input for the city of the user, e.g. `San Francisco`. - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `country: optional string` - The specific create, delete, or update instruction for the apply_patch tool call. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `CreateFile object { diff, path, type }` + - `region: optional string` - Instruction for creating a new file via the apply_patch tool. + Free text input for the region of the user, e.g. `California`. - - `diff: string` + - `timezone: optional string` - Unified diff content to apply when creating the file. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `path: string` + - `type: optional "approximate"` - Path of the file to create relative to the workspace root. + The type of location approximation. Always `approximate`. - - `type: "create_file"` + - `"approximate"` - The operation type. Always `create_file`. + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `"create_file"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `DeleteFile object { path, type }` + - `server_label: string` - Instruction for deleting an existing file via the apply_patch tool. + A label for this MCP server, used to identify it in tool calls. - - `path: string` + - `type: "mcp"` - Path of the file to delete relative to the workspace root. + The type of the MCP tool. Always `mcp`. - - `type: "delete_file"` + - `"mcp"` - The operation type. Always `delete_file`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"delete_file"` + The tool invocation context(s). - - `UpdateFile object { diff, path, type }` + - `"direct"` - Instruction for updating an existing file via the apply_patch tool. + - `"programmatic"` - - `diff: string` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - Unified diff content to apply to the existing file. + List of allowed tool names or a filter object. - - `path: string` + - `McpAllowedTools = array of string` - Path of the file to update relative to the workspace root. + A string array of allowed tool names - - `type: "update_file"` + - `McpToolFilter object { read_only, tool_names }` - The operation type. Always `update_file`. + A filter object to specify which tools are allowed. - - `"update_file"` + - `read_only: optional boolean` - - `status: "in_progress" or "completed"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `tool_names: optional array of string` - - `"in_progress"` + List of allowed tool names. - - `"completed"` + - `authorization: optional string` - - `type: "apply_patch_call"` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - The type of the item. Always `apply_patch_call`. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `"apply_patch_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). - - `id: optional string` + Currently supported `connector_id` values are: - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - 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` - - `agent: optional object { agent_name }` + - `"connector_dropbox"` - The agent that produced this item. + - `"connector_gmail"` - - `agent_name: string` + - `"connector_googlecalendar"` - The canonical name of the agent that produced this item. + - `"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. - - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` + - `always: optional object { read_only, tool_names }` - The streamed output emitted by an apply patch tool call. + A filter object to specify which tools are allowed. - - `call_id: string` + - `read_only: optional boolean` - The unique ID of the apply patch tool call generated by 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. - - `status: "completed" or "failed"` + - `tool_names: optional array of string` - The status of the apply patch tool call output. One of `completed` or `failed`. + List of allowed tool names. - - `"completed"` + - `never: optional object { read_only, tool_names }` - - `"failed"` + A filter object to specify which tools are allowed. - - `type: "apply_patch_call_output"` + - `read_only: optional boolean` - The type of the item. Always `apply_patch_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. - - `"apply_patch_call_output"` + - `tool_names: optional array of string` - - `id: optional string` + List of allowed tool names. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `McpToolApprovalSetting = "always" or "never"` - - `agent: optional object { agent_name }` + 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 agent that produced this item. + - `"always"` - - `agent_name: string` + - `"never"` - The canonical name of the agent that produced this item. + - `server_description: optional string` - - `caller: optional object { type } or object { caller_id, type }` + Optional description of the MCP server, used to provide more context. - The execution context that produced this tool call. + - `server_url: optional string` - - `Direct object { type }` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `type: "direct"` + - `tunnel_id: optional string` - The caller type. Always `direct`. + 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. - - `"direct"` + - `CodeInterpreter object { container, type, allowed_callers }` - - `Program object { caller_id, type }` + A tool that runs Python code to help generate a response to a prompt. - - `caller_id: string` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - The call ID of the program item that produced this tool call. + 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: "program"` + - `string` - The caller type. Always `program`. + The container ID. - - `"program"` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `output: optional string` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `type: "auto"` - - `McpListTools object { id, server_label, tools, 3 more }` + Always `auto`. - A list of tools available on an MCP server. + - `"auto"` - - `id: string` + - `file_ids: optional array of string` - The unique ID of the list. + An optional list of uploaded files to make available to your code. - - `server_label: string` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The label of the MCP server. + The memory limit for the code interpreter container. - - `tools: array of object { input_schema, name, annotations, description }` + - `"1g"` - The tools available on the server. + - `"4g"` - - `input_schema: unknown` + - `"16g"` - The JSON schema describing the tool's input. + - `"64g"` - - `name: string` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - The name of the tool. + Network access policy for the container. - - `annotations: optional unknown` + - `BetaContainerNetworkPolicyDisabled object { type }` - Additional annotations about the tool. + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `description: optional string` + - `type: "code_interpreter"` - The description of the tool. + The type of the code interpreter tool. Always `code_interpreter`. - - `type: "mcp_list_tools"` + - `"code_interpreter"` - The type of the item. Always `mcp_list_tools`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"mcp_list_tools"` + The tool invocation context(s). - - `agent: optional object { agent_name }` + - `"direct"` - The agent that produced this item. + - `"programmatic"` - - `agent_name: string` + - `ProgrammaticToolCalling object { type }` - The canonical name of the agent that produced this item. + - `type: "programmatic_tool_calling"` - - `error: optional string` + The type of the tool. Always `programmatic_tool_calling`. - Error message if the server could not list tools. + - `"programmatic_tool_calling"` - - `McpApprovalRequest object { id, arguments, name, 3 more }` + - `ImageGeneration object { type, action, background, 9 more }` - A request for human approval of a tool invocation. + A tool that generates images using the GPT image models. - - `id: string` + - `type: "image_generation"` - The unique ID of the approval request. + The type of the image generation tool. Always `image_generation`. - - `arguments: string` + - `"image_generation"` - A JSON string of arguments for the tool. + - `action: optional "generate" or "edit" or "auto"` - - `name: string` + Whether to generate a new image or edit an existing image. Default: `auto`. - The name of the tool to run. + - `"generate"` - - `server_label: string` + - `"edit"` - The label of the MCP server making the request. + - `"auto"` - - `type: "mcp_approval_request"` + - `background: optional "transparent" or "opaque" or "auto"` - The type of the item. Always `mcp_approval_request`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `"mcp_approval_request"` + - `"transparent"` - - `agent: optional object { agent_name }` + - `"opaque"` - The agent that produced this item. + - `"auto"` - - `agent_name: string` + - `input_fidelity: optional "high" or "low"` - The canonical name of the agent that produced this item. + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` + - `"high"` - A response to an MCP approval request. + - `"low"` - - `approval_request_id: string` + - `input_image_mask: optional object { file_id, image_url }` - The ID of the approval request being answered. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `approve: boolean` + - `file_id: optional string` - Whether the request was approved. + File ID for the mask image. - - `type: "mcp_approval_response"` + - `image_url: optional string` - The type of the item. Always `mcp_approval_response`. + Base64-encoded mask image. - - `"mcp_approval_response"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `id: optional string` + The image generation model to use. Default: `gpt-image-1`. - The unique ID of the approval response + - `string` - - `agent: optional object { agent_name }` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The agent that produced this item. + The image generation model to use. Default: `gpt-image-1`. - - `agent_name: string` + - `"gpt-image-1"` - The canonical name of the agent that produced this item. + - `"gpt-image-1-mini"` - - `reason: optional string` + - `"gpt-image-1.5"` - Optional reason for the decision. + - `moderation: optional "auto" or "low"` - - `McpCall object { id, arguments, name, 7 more }` + Moderation level for the generated image. Default: `auto`. - An invocation of a tool on an MCP server. + - `"auto"` - - `id: string` + - `"low"` - The unique ID of the tool call. + - `output_compression: optional number` - - `arguments: string` + Compression level for the output image. Default: 100. - A JSON string of the arguments passed to the tool. + - `output_format: optional "png" or "webp" or "jpeg"` - - `name: string` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The name of the tool that was run. + - `"png"` - - `server_label: string` + - `"webp"` - The label of the MCP server running the tool. + - `"jpeg"` - - `type: "mcp_call"` + - `partial_images: optional number` - The type of the item. Always `mcp_call`. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `"mcp_call"` + - `quality: optional "low" or "medium" or "high" or "auto"` - - `agent: optional object { agent_name }` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - The agent that produced this item. + - `"low"` - - `agent_name: string` + - `"medium"` - The canonical name of the agent that produced this item. + - `"high"` - - `approval_request_id: optional string` + - `"auto"` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `error: 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 error from the tool call, if any. + - `string` - - `output: optional string` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - The output from the 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`. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `"1024x1024"` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `"1024x1536"` - - `"in_progress"` + - `"1536x1024"` - - `"completed"` + - `"auto"` - - `"incomplete"` + - `LocalShell object { type }` - - `"calling"` + A tool that allows the model to execute shell commands in a local environment. - - `"failed"` + - `type: "local_shell"` - - `CustomToolCallOutput object { call_id, output, type, 3 more }` + The type of the local shell tool. Always `local_shell`. - The output of a custom tool call from your code, being sent back to the model. + - `"local_shell"` - - `call_id: string` + - `Shell object { type, allowed_callers, environment }` - The call ID, used to map this custom tool call output to a custom tool call. + A tool that allows the model to execute shell commands. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `type: "shell"` - 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 shell tool. Always `shell`. - - `StringOutput = string` + - `"shell"` - A string of the output of the custom tool call. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The tool invocation context(s). - Text, image, or file output of the custom tool call. + - `"direct"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `"programmatic"` - A text input to the model. + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `BetaLocalEnvironment object { type, skills }` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `BetaContainerReference object { container_id, type }` - A file input to the model. + - `Custom object { name, type, allowed_callers, 3 more }` - - `type: "custom_tool_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 custom tool call output. Always `custom_tool_call_output`. + - `name: string` - - `"custom_tool_call_output"` + The name of the custom tool, used to identify it in tool calls. - - `id: optional string` + - `type: "custom"` - The unique ID of the custom tool call output in the OpenAI platform. + The type of the custom tool. Always `custom`. - - `agent: optional object { agent_name }` + - `"custom"` - The agent that produced this item. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `agent_name: string` + The tool invocation context(s). - The canonical name of the agent that produced this item. + - `"direct"` - - `caller: optional object { type } or object { caller_id, type }` + - `"programmatic"` - The execution context that produced this tool call. + - `defer_loading: optional boolean` - - `Direct object { type }` + Whether this tool should be deferred and discovered via tool search. - - `type: "direct"` + - `description: optional string` - The caller type. Always `direct`. + Optional description of the custom tool, used to provide more context. - - `"direct"` + - `format: optional object { type } or object { definition, syntax, type }` - - `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"` - The caller type. Always `program`. + Unconstrained text format. Always `text`. - - `"program"` + - `"text"` - - `CustomToolCall object { call_id, input, name, 5 more }` + - `Grammar object { definition, syntax, type }` - A call to a custom tool created by the model. + A grammar defined by the user. - - `call_id: string` + - `definition: string` - An identifier used to map this custom tool call to a tool call output. + The grammar definition. - - `input: string` + - `syntax: "lark" or "regex"` - The input for the custom tool call generated by the model. + The syntax of the grammar definition. One of `lark` or `regex`. - - `name: string` + - `"lark"` - The name of the custom tool being called. + - `"regex"` - - `type: "custom_tool_call"` + - `type: "grammar"` - The type of the custom tool call. Always `custom_tool_call`. + Grammar format. Always `grammar`. - - `"custom_tool_call"` + - `"grammar"` - - `id: optional string` + - `Namespace object { description, name, tools, type }` - The unique ID of the custom tool call in the OpenAI platform. + Groups function/custom tools under a shared namespace. - - `agent: optional object { agent_name }` + - `description: string` - The agent that produced this item. + A description of the namespace shown to the model. - - `agent_name: string` + - `name: string` - The canonical name of the agent that produced this item. + The namespace name used in tool calls (for example, `crm`). - - `caller: optional object { type } or object { caller_id, type }` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - The execution context that produced this tool call. + The function/custom tools available inside this namespace. - - `Direct object { type }` + - `Function object { name, type, allowed_callers, 5 more }` - - `type: "direct"` + - `name: string` - - `"direct"` + - `type: "function"` - - `Program object { caller_id, type }` + - `"function"` - - `caller_id: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The call ID of the program item that produced this tool call. + The tool invocation context(s). - - `type: "program"` + - `"direct"` - - `"program"` + - `"programmatic"` - - `namespace: optional string` + - `defer_loading: optional boolean` - The namespace of the custom tool being called. + Whether this function should be deferred and discovered via tool search. - - `CompactionTrigger object { type, agent }` + - `description: optional string` - Compacts the current context. Must be the final input item. + - `output_schema: optional map[unknown]` - - `type: "compaction_trigger"` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - The type of the item. Always `compaction_trigger`. + - `parameters: optional unknown` - - `"compaction_trigger"` + - `strict: optional boolean` - - `agent: optional object { agent_name }` + 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 agent that produced this item. + - `Custom object { name, type, allowed_callers, 3 more }` - - `agent_name: string` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - The canonical name of the agent that produced this item. + - `name: string` - - `ItemReference object { id, agent, type }` + The name of the custom tool, used to identify it in tool calls. - An internal identifier for an item to reference. + - `type: "custom"` - - `id: string` + The type of the custom tool. Always `custom`. - The ID of the item to reference. + - `"custom"` - - `agent: optional object { agent_name }` + - `allowed_callers: optional array of "direct" or "programmatic"` - The agent that produced this item. + The tool invocation context(s). - - `agent_name: string` + - `"direct"` - The canonical name of the agent that produced this item. + - `"programmatic"` - - `type: optional "item_reference"` + - `defer_loading: optional boolean` - The type of item to reference. Always `item_reference`. + Whether this tool should be deferred and discovered via tool search. - - `"item_reference"` + - `description: optional string` - - `Program object { id, call_id, code, 3 more }` + Optional description of the custom tool, used to provide more context. - - `id: string` + - `format: optional object { type } or object { definition, syntax, type }` - The unique ID of this program item. + The input format for the custom tool. Default is unconstrained text. - - `call_id: string` + - `Text object { type }` - The stable call ID of the program item. + Unconstrained free-form text. - - `code: string` + - `type: "text"` - The JavaScript source executed by programmatic tool calling. + Unconstrained text format. Always `text`. - - `fingerprint: string` + - `"text"` - Opaque program replay fingerprint that must be round-tripped. + - `Grammar object { definition, syntax, type }` - - `type: "program"` + A grammar defined by the user. - The item type. Always `program`. + - `definition: string` - - `"program"` + The grammar definition. - - `agent: optional object { agent_name }` + - `syntax: "lark" or "regex"` - The agent that produced this item. + The syntax of the grammar definition. One of `lark` or `regex`. - - `agent_name: string` + - `"lark"` - The canonical name of the agent that produced this item. + - `"regex"` - - `ProgramOutput object { id, call_id, result, 3 more }` + - `type: "grammar"` - - `id: string` + Grammar format. Always `grammar`. - The unique ID of this program output item. + - `"grammar"` - - `call_id: string` + - `type: "namespace"` - The call ID of the program item. + The type of the tool. Always `namespace`. - - `result: string` + - `"namespace"` - The result produced by the program item. + - `ToolSearch object { type, description, execution, parameters }` - - `status: "completed" or "incomplete"` + Hosted or BYOT tool search configuration for deferred tools. - The terminal status of the program output. + - `type: "tool_search"` - - `"completed"` + The type of the tool. Always `tool_search`. - - `"incomplete"` + - `"tool_search"` - - `type: "program_output"` + - `description: optional string` - The item type. Always `program_output`. + Description shown to the model for a client-executed tool search tool. - - `"program_output"` + - `execution: optional "server" or "client"` - - `agent: optional object { agent_name }` + Whether tool search is executed by the server or by the client. - The agent that produced this item. + - `"server"` - - `agent_name: string` + - `"client"` - The canonical name of the agent that produced this item. + - `parameters: optional unknown` - - `metadata: map[string]` + Parameter schema for a client-executed tool search tool. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + 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). - - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - 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. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` + - `"web_search_preview"` - 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. + - `"web_search_preview_2025_03_11"` - - `"gpt-5.6-sol"` + - `search_content_types: optional array of "text" or "image"` - - `"gpt-5.6-terra"` + - `"text"` - - `"gpt-5.6-luna"` + - `"image"` - - `"gpt-5.4"` + - `search_context_size: optional "low" or "medium" or "high"` - - `"gpt-5.4-mini"` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `"gpt-5.4-nano"` + - `"low"` - - `"gpt-5.4-mini-2026-03-17"` + - `"medium"` - - `"gpt-5.4-nano-2026-03-17"` + - `"high"` - - `"gpt-5.3-chat-latest"` + - `user_location: optional object { type, city, country, 2 more }` - - `"gpt-5.2"` + The user's location. - - `"gpt-5.2-2025-12-11"` + - `type: "approximate"` - - `"gpt-5.2-chat-latest"` + The type of location approximation. Always `approximate`. - - `"gpt-5.2-pro"` + - `"approximate"` - - `"gpt-5.2-pro-2025-12-11"` + - `city: optional string` - - `"gpt-5.1"` + Free text input for the city of the user, e.g. `San Francisco`. - - `"gpt-5.1-2025-11-13"` + - `country: optional string` - - `"gpt-5.1-codex"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"gpt-5.1-mini"` + - `region: optional string` - - `"gpt-5.1-chat-latest"` + Free text input for the region of the user, e.g. `California`. - - `"gpt-5"` + - `timezone: optional string` - - `"gpt-5-mini"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"gpt-5-nano"` + - `ApplyPatch object { type, allowed_callers }` - - `"gpt-5-2025-08-07"` + Allows the assistant to create, delete, or update files using unified diffs. - - `"gpt-5-mini-2025-08-07"` + - `type: "apply_patch"` - - `"gpt-5-nano-2025-08-07"` + The type of the tool. Always `apply_patch`. - - `"gpt-5-chat-latest"` + - `"apply_patch"` - - `"gpt-4.1"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"gpt-4.1-mini"` + The tool invocation context(s). - - `"gpt-4.1-nano"` + - `"direct"` - - `"gpt-4.1-2025-04-14"` + - `"programmatic"` - - `"gpt-4.1-mini-2025-04-14"` + - `top_p: number` - - `"gpt-4.1-nano-2025-04-14"` + 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. - - `"o4-mini"` + We generally recommend altering this or `temperature` but not both. - - `"o4-mini-2025-04-16"` + - `background: optional boolean` - - `"o3"` + Whether to run the model response in the background. + [Learn more](/docs/guides/background). - - `"o3-2025-04-16"` + - `completed_at: optional number` - - `"o3-mini"` + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - - `"o3-mini-2025-01-31"` + - `conversation: optional object { id }` - - `"o1"` + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - - `"o1-2024-12-17"` + - `id: string` - - `"o1-preview"` + The unique ID of the conversation that this response was associated with. - - `"o1-preview-2024-09-12"` + - `max_output_tokens: optional number` - - `"o1-mini"` + 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). - - `"o1-mini-2024-09-12"` + - `max_tool_calls: optional number` - - `"gpt-4o"` + 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. - - `"gpt-4o-2024-11-20"` + - `moderation: optional object { input, output }` - - `"gpt-4o-2024-08-06"` + Moderation results for the response input and output, if moderated completions were requested. - - `"gpt-4o-2024-05-13"` + - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - - `"gpt-4o-audio-preview"` + Moderation for the response input. - - `"gpt-4o-audio-preview-2024-10-01"` + - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` - - `"gpt-4o-audio-preview-2024-12-17"` + A moderation result produced for the response input or output. - - `"gpt-4o-audio-preview-2025-06-03"` + - `categories: map[boolean]` - - `"gpt-4o-mini-audio-preview"` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `"gpt-4o-mini-audio-preview-2024-12-17"` + - `category_applied_input_types: map[array of "text" or "image"]` - - `"gpt-4o-search-preview"` + Which modalities of input are reflected by the score for each category. - - `"gpt-4o-mini-search-preview"` + - `"text"` - - `"gpt-4o-search-preview-2025-03-11"` + - `"image"` - - `"gpt-4o-mini-search-preview-2025-03-11"` + - `category_scores: map[number]` - - `"chatgpt-4o-latest"` + A dictionary of moderation categories to scores. - - `"codex-mini-latest"` + - `flagged: boolean` - - `"gpt-4o-mini"` + A boolean indicating whether the content was flagged by any category. - - `"gpt-4o-mini-2024-07-18"` + - `model: string` - - `"gpt-4-turbo"` + The moderation model that produced this result. - - `"gpt-4-turbo-2024-04-09"` + - `type: "moderation_result"` - - `"gpt-4-0125-preview"` + The object type, which was always `moderation_result` for successful moderation results. - - `"gpt-4-turbo-preview"` + - `"moderation_result"` - - `"gpt-4-1106-preview"` + - `Error object { code, message, type }` - - `"gpt-4-vision-preview"` + An error produced while attempting moderation for the response input or output. - - `"gpt-4"` + - `code: string` - - `"gpt-4-0314"` + The error code. - - `"gpt-4-0613"` + - `message: string` - - `"gpt-4-32k"` + The error message. - - `"gpt-4-32k-0314"` + - `type: "error"` - - `"gpt-4-32k-0613"` + The object type, which was always `error` for moderation failures. - - `"gpt-3.5-turbo"` + - `"error"` - - `"gpt-3.5-turbo-16k"` + - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - - `"gpt-3.5-turbo-0301"` + Moderation for the response output. - - `"gpt-3.5-turbo-0613"` + - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` - - `"gpt-3.5-turbo-1106"` + A moderation result produced for the response input or output. - - `"gpt-3.5-turbo-0125"` + - `categories: map[boolean]` - - `"gpt-3.5-turbo-16k-0613"` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `"o1-pro"` + - `category_applied_input_types: map[array of "text" or "image"]` - - `"o1-pro-2025-03-19"` + Which modalities of input are reflected by the score for each category. - - `"o3-pro"` + - `"text"` - - `"o3-pro-2025-06-10"` + - `"image"` - - `"o3-deep-research"` + - `category_scores: map[number]` - - `"o3-deep-research-2025-06-26"` + A dictionary of moderation categories to scores. - - `"o4-mini-deep-research"` + - `flagged: boolean` - - `"o4-mini-deep-research-2025-06-26"` + A boolean indicating whether the content was flagged by any category. - - `"computer-use-preview"` + - `model: string` - - `"computer-use-preview-2025-03-11"` + The moderation model that produced this result. - - `"gpt-5-codex"` + - `type: "moderation_result"` - - `"gpt-5-pro"` + The object type, which was always `moderation_result` for successful moderation results. - - `"gpt-5-pro-2025-10-06"` + - `"moderation_result"` - - `"gpt-5.1-codex-max"` + - `Error object { code, message, type }` - - `string` + An error produced while attempting moderation for the response input or output. - - `object: "response"` + - `code: string` - The object type of this resource - always set to `response`. + The error code. - - `"response"` + - `message: string` - - `output: array of BetaResponseOutputItem` + The error message. - An array of content items generated by the model. + - `type: "error"` - - 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. + The object type, which was always `error` for moderation failures. - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + - `"error"` - An output message from the model. + - `output_text: optional string` - - `FileSearchCall object { id, queries, status, 3 more }` + 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 results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + - `previous_response_id: optional string` - - `id: 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`. - The unique ID of the file search tool call. + - `prompt: optional BetaResponsePrompt` - - `queries: array of string` + Reference to a prompt template and its variables. + [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). - The queries used to search for files. + - `id: string` - - `status: "in_progress" or "searching" or "completed" or 2 more` + The unique identifier of the prompt template to use. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` - - `"in_progress"` + 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. - - `"searching"` + - `string` - - `"completed"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `"incomplete"` + A text input to the model. - - `"failed"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `type: "file_search_call"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - The type of the file search tool call. Always `file_search_call`. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `"file_search_call"` + A file input to the model. - - `agent: optional object { agent_name }` + - `version: optional string` - The agent that produced this item. + Optional version of the prompt template. - - `agent_name: string` + - `prompt_cache_key: optional string` - The canonical name of the agent that produced this item. + 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). - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `prompt_cache_options: optional object { mode, ttl }` - The results of the file search tool call. + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `attributes: optional map[string or number or boolean]` + - `mode: "implicit" or "explicit"` - 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. + Whether implicit prompt-cache breakpoints were enabled. - - `string` + - `"implicit"` - - `number` + - `"explicit"` - - `boolean` + - `ttl: "30m"` - - `file_id: optional string` + The minimum lifetime applied to each cache breakpoint. - The unique ID of the file. + - `"30m"` - - `filename: optional string` + - `prompt_cache_retention: optional "in_memory" or "24h"` - The name of the file. + Deprecated. Use `prompt_cache_options.ttl` instead. - - `score: optional number` + 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 relevance score of the file - a value between 0 and 1. + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `text: optional string` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - The text that was retrieved from the file. + - `"in_memory"` - - `FunctionCall object { arguments, call_id, name, 6 more }` + - `"24h"` - A tool call to run a function. See the - [function calling guide](/docs/guides/function-calling) for more information. + - `reasoning: optional object { context, effort, generate_summary, 2 more }` - - `arguments: string` + **gpt-5 and o-series models only** - A JSON string of the arguments to pass to the function. + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `call_id: string` + - `context: optional "auto" or "current_turn" or "all_turns"` - The unique ID of the function tool call generated by the model. + 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`. - - `name: string` + When returned on a response, this is the effective reasoning context mode + used for the response. - The name of the function to run. + - `"auto"` - - `type: "function_call"` + - `"current_turn"` - The type of the function tool call. Always `function_call`. + - `"all_turns"` - - `"function_call"` + - `effort: optional "none" or "minimal" or "low" or 4 more` - - `id: 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 unique ID of the function tool call. + - `"none"` - - `agent: optional object { agent_name }` + - `"minimal"` - The agent that produced this item. + - `"low"` - - `agent_name: string` + - `"medium"` - The canonical name of the agent that produced this item. + - `"high"` - - `caller: optional object { type } or object { caller_id, type }` + - `"xhigh"` - The execution context that produced this tool call. + - `"max"` - - `Direct object { type }` + - `generate_summary: optional "auto" or "concise" or "detailed"` - - `type: "direct"` + **Deprecated:** use `summary` instead. - - `"direct"` + 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`. - - `Program object { caller_id, type }` + - `"auto"` - - `caller_id: string` + - `"concise"` - The call ID of the program item that produced this tool call. + - `"detailed"` - - `type: "program"` + - `mode: optional string or "standard" or "pro"` - - `"program"` + Controls the reasoning execution mode for the request. - - `namespace: optional string` + When returned on a response, this is the effective execution mode. - The namespace of the function to run. + - `string` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"standard" or "pro"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Controls the reasoning execution mode for the request. - - `"in_progress"` + When returned on a response, this is the effective execution mode. - - `"completed"` + - `"standard"` - - `"incomplete"` + - `"pro"` - - `FunctionCallOutput object { id, call_id, output, 5 more }` + - `summary: optional "auto" or "concise" or "detailed"` - - `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 call tool output. + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `call_id: string` + - `"auto"` - The unique ID of the function tool call generated by the model. + - `"concise"` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `"detailed"` - The output from the function call generated by your code. - Can be a string or an list of output content. + - `safety_identifier: optional string` - - `StringOutput = 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). - A string of the output of the function call. + - `service_tier: optional "auto" or "default" or "flex" or 2 more` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + Specifies the processing type used for serving the request. - Text, image, or file output of the function 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'. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + 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 text input to the model. + - `"auto"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `"default"` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `"flex"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `"scale"` - A file input to the model. + - `"priority"` - - `status: "in_progress" or "completed" or "incomplete"` + - `status: optional BetaResponseStatus` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. + + - `"completed"` + + - `"failed"` - `"in_progress"` - - `"completed"` + - `"cancelled"` + + - `"queued"` - `"incomplete"` - - `type: "function_call_output"` + - `text: optional BetaResponseTextConfig` - The type of the function tool call output. Always `function_call_output`. + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `"function_call_output"` + - [Text inputs and outputs](/docs/guides/text) + - [Structured Outputs](/docs/guides/structured-outputs) - - `agent: optional object { agent_name }` + - `format: optional BetaResponseFormatTextConfig` - The agent that produced this item. + An object specifying the format that the model must output. - - `agent_name: 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 canonical name of the agent that produced this item. + The default format is `{ "type": "text" }` with no additional options. - - `caller: optional object { type } or object { caller_id, type }` + **Not recommended for gpt-4o and newer models:** - The execution context that produced this tool call. + 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. - - `Direct object { type }` + - `Text object { type }` - - `type: "direct"` + Default response format. Used to generate text responses. - The caller type. Always `direct`. + - `type: "text"` - - `"direct"` + The type of response format being defined. Always `text`. - - `Program object { caller_id, type }` + - `"text"` - - `caller_id: string` + - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` - The call ID of the program item that produced this tool call. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `type: "program"` + - `name: string` - The caller type. Always `program`. + 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. - - `"program"` + - `schema: map[unknown]` - - `created_by: optional string` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - The identifier of the actor that created the item. + - `type: "json_schema"` - - `AgentMessage object { id, author, content, 3 more }` + The type of response format being defined. Always `json_schema`. - - `id: string` + - `"json_schema"` - The unique ID of the agent message. + - `description: optional string` - - `author: string` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The sending agent identity. + - `strict: optional boolean` - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + 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). - Encrypted content sent between agents. + - `JSONObject object { type }` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + 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. - A text input to the model. + - `type: "json_object"` - - `BetaResponseOutputText object { annotations, logprobs, text, type }` + The type of response format being defined. Always `json_object`. - A text output from the model. + - `"json_object"` - - `Text object { text, type }` + - `verbosity: optional "low" or "medium" or "high"` - A text content. + 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`. - - `text: string` + - `"low"` - - `type: "text"` + - `"medium"` - - `"text"` + - `"high"` - - `SummaryText object { text, type }` + - `top_logprobs: optional number` - A summary text from the model. + 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. - - `text: string` + - `truncation: optional "auto" or "disabled"` - A summary of the reasoning output from the model so far. + The truncation strategy to use for the model response. - - `type: "summary_text"` + - `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 type of the object. Always `summary_text`. + - `"auto"` - - `"summary_text"` + - `"disabled"` - - `ReasoningText object { text, type }` + - `usage: optional BetaResponseUsage` - Reasoning text from the model. + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `text: string` + - `input_tokens: number` - The reasoning text from the model. + The number of input tokens. - - `type: "reasoning_text"` + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` - The type of the reasoning text. Always `reasoning_text`. + A detailed breakdown of the input tokens. - - `"reasoning_text"` + - `cache_write_tokens: number` - - `BetaResponseOutputRefusal object { refusal, type }` + The number of input tokens that were written to the cache. - A refusal from the model. + - `cached_tokens: number` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + The number of tokens that were retrieved from the cache. + [More on prompt caching](/docs/guides/prompt-caching). - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `output_tokens: number` - - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` + The number of output tokens. - A screenshot of a computer. + - `output_tokens_details: object { reasoning_tokens }` - - `detail: "low" or "high" or "auto" or "original"` + A detailed breakdown of the output tokens. - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `reasoning_tokens: number` - - `"low"` + The number of reasoning tokens. - - `"high"` + - `total_tokens: number` - - `"auto"` + The total number of tokens used. - - `"original"` + - `user: optional string` - - `file_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 identifier of an uploaded file that contains the screenshot. +### Example - - `image_url: string` +```http +curl https://api.openai.com/v1/responses/$RESPONSE_ID \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - The URL of the screenshot image. +#### Response - - `type: "computer_screenshot"` +```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", + "agent": { + "agent_name": "agent_name" + }, + "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" +} +``` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. +### Example - - `"computer_screenshot"` +```http +curl https://api.openai.com/v1/responses/resp_123 \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `prompt_cache_breakpoint: optional object { mode }` +#### Response - 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. +```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": {} +} +``` - - `mode: "explicit"` +## Domain Types - The breakpoint mode. Always `explicit`. +### Beta Compacted Response - - `"explicit"` +- `BetaCompactedResponse object { id, created_at, object, 2 more }` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `id: string` - A file input to the model. + The unique identifier for the compacted response. - - `EncryptedContent object { encrypted_content, type }` + - `created_at: number` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + Unix timestamp (in seconds) when the compacted conversation was created. - - `encrypted_content: string` + - `object: "response.compaction"` - Opaque encrypted content. + The object type. Always `response.compaction`. - - `type: "encrypted_content"` + - `"response.compaction"` - The type of the input item. Always `encrypted_content`. + - `output: array of object { id, content, role, 4 more } or object { id, call_id, code, 3 more } or object { id, call_id, result, 3 more } or 28 more` - - `"encrypted_content"` + The compacted list of output items. - - `recipient: string` + - `Message object { id, content, role, 4 more }` - The destination agent identity. + A message to or from the model. - - `type: "agent_message"` + - `id: string` - The type of the item. Always `agent_message`. + The unique ID of the message. - - `"agent_message"` + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - - `agent: optional object { agent_name }` + The content of the message - The agent that produced this item. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `agent_name: string` + A text input to the model. - The canonical name of the agent that produced this item. + - `text: string` - - `MultiAgentCall object { id, action, arguments, 3 more }` + The text input to the model. - - `id: string` + - `type: "input_text"` - The unique ID of the multi-agent call item. + The type of the input item. Always `input_text`. - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `"input_text"` - The multi-agent action to execute. + - `prompt_cache_breakpoint: optional object { mode }` - - `"spawn_agent"` + 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. - - `"interrupt_agent"` + - `mode: "explicit"` - - `"list_agents"` + The breakpoint mode. Always `explicit`. - - `"send_message"` + - `"explicit"` - - `"followup_task"` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - - `"wait_agent"` + A text output from the model. - - `arguments: 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 }` - The JSON string of arguments generated for the action. + The annotations of the text output. - - `call_id: string` + - `FileCitation object { file_id, filename, index, type }` - The unique ID linking this call to its output. + A citation to a file. - - `type: "multi_agent_call"` + - `file_id: string` - The type of the multi-agent call. Always `multi_agent_call`. + The ID of the file. - - `"multi_agent_call"` + - `filename: string` - - `agent: optional object { agent_name }` + The filename of the file cited. - The agent that produced this item. + - `index: number` - - `agent_name: string` + The index of the file in the list of files. - The canonical name of the agent that produced this item. + - `type: "file_citation"` - - `MultiAgentCallOutput object { id, action, call_id, 3 more }` + The type of the file citation. Always `file_citation`. - - `id: string` + - `"file_citation"` - The unique ID of the multi-agent call output item. + - `URLCitation object { end_index, start_index, title, 2 more }` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + A citation for a web resource used to generate a model response. - The multi-agent action that produced this result. + - `end_index: number` - - `"spawn_agent"` + The index of the last character of the URL citation in the message. - - `"interrupt_agent"` + - `start_index: number` - - `"list_agents"` + The index of the first character of the URL citation in the message. - - `"send_message"` + - `title: string` - - `"followup_task"` + The title of the web resource. - - `"wait_agent"` + - `type: "url_citation"` - - `call_id: string` + The type of the URL citation. Always `url_citation`. - The unique ID of the multi-agent call. + - `"url_citation"` - - `output: array of BetaResponseOutputText` + - `url: string` - Text output returned by the multi-agent action. + The URL of the web resource. - - `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 }` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - The annotations of the text output. + A citation for a container file used to generate a model response. - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `container_id: string` - - `text: string` + The ID of the container file. - The text output from the model. + - `end_index: number` - - `type: "output_text"` + The index of the last character of the container file citation in the message. - The type of the output text. Always `output_text`. + - `file_id: string` - - `type: "multi_agent_call_output"` + The ID of the file. - The type of the multi-agent result. Always `multi_agent_call_output`. + - `filename: string` - - `"multi_agent_call_output"` + The filename of the container file cited. - - `agent: optional object { agent_name }` + - `start_index: number` - The agent that produced this item. + The index of the first character of the container file citation in the message. - - `agent_name: string` + - `type: "container_file_citation"` - The canonical name of the agent that produced this item. + The type of the container file citation. Always `container_file_citation`. - - `WebSearchCall object { id, action, status, 2 more }` + - `"container_file_citation"` - The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + - `FilePath object { file_id, index, type }` - - `id: string` + A path to a file. - The unique ID of the web search tool call. + - `file_id: string` - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + The ID of the file. - 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). + - `index: number` - - `Search object { type, queries, query, sources }` + The index of the file in the list of files. - Action type "search" - Performs a web search query. + - `type: "file_path"` - - `type: "search"` + The type of the file path. Always `file_path`. - The action type. + - `"file_path"` - - `"search"` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - - `queries: optional array of string` + - `token: string` - The search queries. + - `bytes: array of number` - - `query: optional string` + - `logprob: number` - The search query. + - `top_logprobs: array of object { token, bytes, logprob }` - - `sources: optional array of object { type, url }` + - `token: string` - The sources used in the search. + - `bytes: array of number` - - `type: "url"` + - `logprob: number` - The type of source. Always `url`. + - `text: string` - - `"url"` + The text output from the model. - - `url: string` + - `type: "output_text"` - The URL of the source. + The type of the output text. Always `output_text`. - - `OpenPage object { type, url }` + - `"output_text"` - Action type "open_page" - Opens a specific URL from search results. + - `Text object { text, type }` - - `type: "open_page"` + A text content. - The action type. + - `text: string` - - `"open_page"` + - `type: "text"` - - `url: optional string` + - `"text"` - The URL opened by the model. + - `SummaryText object { text, type }` - - `FindInPage object { pattern, type, url }` + A summary text from the model. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `text: string` - - `pattern: string` + A summary of the reasoning output from the model so far. - The pattern or text to search for within the page. + - `type: "summary_text"` - - `type: "find_in_page"` + The type of the object. Always `summary_text`. - The action type. + - `"summary_text"` - - `"find_in_page"` + - `ReasoningText object { text, type }` - - `url: string` + Reasoning text from the model. - The URL of the page searched for the pattern. + - `text: string` - - `status: "in_progress" or "searching" or "completed" or "failed"` + The reasoning text from the model. - The status of the web search tool call. + - `type: "reasoning_text"` - - `"in_progress"` + The type of the reasoning text. Always `reasoning_text`. - - `"searching"` + - `"reasoning_text"` - - `"completed"` + - `BetaResponseOutputRefusal object { refusal, type }` - - `"failed"` + A refusal from the model. - - `type: "web_search_call"` + - `refusal: string` - The type of the web search tool call. Always `web_search_call`. + The refusal explanation from the model. - - `"web_search_call"` + - `type: "refusal"` - - `agent: optional object { agent_name }` + The type of the refusal. Always `refusal`. - The agent that produced this item. + - `"refusal"` - - `agent_name: string` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - The canonical name of the agent that produced this item. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + - `detail: "low" or "high" or "auto" or "original"` - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + 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 ID of the computer call. + - `"high"` - - `call_id: string` + - `"auto"` - An identifier used when responding to the tool call with output. + - `"original"` - - `pending_safety_checks: array of object { id, code, message }` + - `type: "input_image"` - The pending safety checks for the computer call. + The type of the input item. Always `input_image`. - - `id: string` + - `"input_image"` - The ID of the pending safety check. + - `file_id: optional string` - - `code: optional string` + The ID of the file to be sent to the model. - The type of the pending safety check. + - `image_url: optional string` - - `message: 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. - Details about the pending safety check. + - `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 item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `mode: "explicit"` - - `"in_progress"` + The breakpoint mode. Always `explicit`. - - `"completed"` + - `"explicit"` - - `"incomplete"` + - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` - - `type: "computer_call"` + A screenshot of a computer. - The type of the computer call. Always `computer_call`. + - `detail: "low" or "high" or "auto" or "original"` - - `"computer_call"` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `action: optional BetaComputerAction` + - `"low"` - A click action. + - `"high"` - - `actions: optional BetaComputerActionList` + - `"auto"` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `"original"` - - `agent: optional object { agent_name }` + - `file_id: string` - The agent that produced this item. + The identifier of an uploaded file that contains the screenshot. - - `agent_name: string` + - `image_url: string` - The canonical name of the agent that produced this item. + The URL of the screenshot image. - - `ComputerCallOutput object { id, call_id, output, 5 more }` + - `type: "computer_screenshot"` - - `id: string` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - The unique ID of the computer call tool output. + - `"computer_screenshot"` - - `call_id: string` + - `prompt_cache_breakpoint: optional object { mode }` - The ID of the computer tool call that produced the 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. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `mode: "explicit"` - A computer screenshot image used with the computer use tool. + The breakpoint mode. Always `explicit`. - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + - `"explicit"` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `"completed"` + A file input to the model. - - `"incomplete"` + - `type: "input_file"` - - `"failed"` + The type of the input item. Always `input_file`. - - `"in_progress"` + - `"input_file"` - - `type: "computer_call_output"` + - `detail: optional "auto" or "low" or "high"` - The type of the computer tool call output. Always `computer_call_output`. + 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`. - - `"computer_call_output"` + - `"auto"` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `"low"` - The safety checks reported by the API that have been acknowledged by the - developer. + - `"high"` - - `id: string` + - `file_data: optional string` - The ID of the pending safety check. + The content of the file to be sent to the model. - - `code: optional string` + - `file_id: optional string` - The type of the pending safety check. + The ID of the file to be sent to the model. - - `message: optional string` + - `file_url: optional string` - Details about the pending safety check. + The URL of the file to be sent to the model. - - `agent: optional object { agent_name }` + - `filename: optional string` - The agent that produced this item. + The name of the file to be sent to the model. - - `agent_name: string` + - `prompt_cache_breakpoint: optional object { mode }` - The canonical name of the agent that produced this item. + 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. - - `created_by: optional string` + - `mode: "explicit"` - The identifier of the actor that created the item. + The breakpoint mode. Always `explicit`. - - `Reasoning object { id, summary, type, 4 more }` + - `"explicit"` - 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). + - `EncryptedContent object { encrypted_content, type }` - - `id: string` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - The unique identifier of the reasoning content. + - `encrypted_content: string` - - `summary: array of object { text, type }` + Opaque encrypted content. - Reasoning summary content. + - `type: "encrypted_content"` - - `text: string` + The type of the input item. Always `encrypted_content`. - A summary of the reasoning output from the model so far. + - `"encrypted_content"` - - `type: "summary_text"` + - `role: "unknown" or "user" or "assistant" or 5 more` - The type of the object. Always `summary_text`. + The role of the message. One of `unknown`, `user`, `assistant`, `system`, `critic`, `discriminator`, `developer`, or `tool`. - - `"summary_text"` + - `"unknown"` - - `type: "reasoning"` + - `"user"` - The type of the object. Always `reasoning`. + - `"assistant"` - - `"reasoning"` + - `"system"` - - `agent: optional object { agent_name }` + - `"critic"` - The agent that produced this item. + - `"discriminator"` - - `agent_name: string` + - `"developer"` - The canonical name of the agent that produced this item. + - `"tool"` - - `content: optional array of object { text, type }` + - `status: "in_progress" or "completed" or "incomplete"` - Reasoning text content. + The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `text: string` + - `"in_progress"` - The reasoning text from the model. + - `"completed"` - - `type: "reasoning_text"` + - `"incomplete"` - The type of the reasoning text. Always `reasoning_text`. + - `type: "message"` - - `"reasoning_text"` + The type of the message. Always set to `message`. - - `encrypted_content: optional string` + - `"message"` - 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. + - `agent: optional object { agent_name }` - - `status: optional "in_progress" or "completed" or "incomplete"` + The agent that produced this item. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `agent_name: string` - - `"in_progress"` + The canonical name of the agent that produced this item. - - `"completed"` + - `phase: optional "commentary" or "final_answer"` - - `"incomplete"` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + + - `"commentary"` + + - `"final_answer"` - `Program object { id, call_id, code, 3 more }` @@ -62023,6 +59259,178 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. + - `FunctionCall object { arguments, call_id, name, 6 more }` + + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. + + - `arguments: string` + + A JSON string of the arguments to pass to the function. + + - `call_id: string` + + The unique ID of the function tool call generated by the model. + + - `name: string` + + The name of the function to run. + + - `type: "function_call"` + + The type of the function tool call. Always `function_call`. + + - `"function_call"` + + - `id: optional string` + + The unique ID of the function tool call. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + + - `namespace: optional string` + + The namespace of the function to run. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `MultiAgentCall object { id, action, arguments, 3 more }` + + - `id: string` + + The unique ID of the multi-agent call item. + + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + + The multi-agent action to execute. + + - `"spawn_agent"` + + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` + + - `arguments: string` + + The JSON string of arguments generated for the action. + + - `call_id: string` + + The unique ID linking this call to its output. + + - `type: "multi_agent_call"` + + The type of the multi-agent call. Always `multi_agent_call`. + + - `"multi_agent_call"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `MultiAgentCallOutput object { id, action, call_id, 3 more }` + + - `id: string` + + The unique ID of the multi-agent call output item. + + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + + The multi-agent action that produced this result. + + - `"spawn_agent"` + + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` + + - `call_id: string` + + The unique ID of the multi-agent call. + + - `output: array of BetaResponseOutputText` + + Text output returned by the multi-agent action. + + - `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. + + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + + - `text: string` + + The text output from the model. + + - `type: "output_text"` + + The type of the output text. Always `output_text`. + + - `type: "multi_agent_call_output"` + + The type of the multi-agent result. Always `multi_agent_call_output`. + + - `"multi_agent_call_output"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + - `ToolSearchCall object { id, arguments, call_id, 5 more }` - `id: string` @@ -62624,8 +60032,40 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `BetaContainerNetworkPolicyDisabled object { type }` + - `type: "disabled"` + + Disable outbound network access. Always `disabled`. + + - `"disabled"` + - `BetaContainerNetworkPolicyAllowlist 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 BetaContainerNetworkPolicyDomainSecret` + + 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`. @@ -62806,10 +60246,128 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `BetaContainerAuto 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 BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `BetaContainerNetworkPolicyDisabled object { type }` + + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `skills: optional array of BetaSkillReference or BetaInlineSkill` + + An optional list of skills referenced by id or inline data. + + - `BetaSkillReference 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. + + - `BetaInlineSkill object { description, name, source, type }` + + - `description: string` + + The description of the skill. + + - `name: string` + + The name of the skill. + + - `source: BetaInlineSkillSource` + + 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"` + - `BetaLocalEnvironment object { type, skills }` + - `type: "local"` + + Use a local computer environment. + + - `"local"` + + - `skills: optional array of BetaLocalSkill` + + 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. + - `BetaContainerReference 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) @@ -64145,142 +61703,141 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `Compaction object { id, encrypted_content, type, 2 more }` - - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + - `AgentMessage object { id, author, content, 3 more }` - `id: string` - The unique ID of the compaction item. + The unique ID of the agent message. - - `encrypted_content: string` + - `author: string` - The encrypted content that was produced by compaction. + The sending agent identity. - - `type: "compaction"` + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - The type of the item. Always `compaction`. + Encrypted content sent between agents. - - `"compaction"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `agent: optional object { agent_name }` + A text input to the model. - The agent that produced this item. + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - - `agent_name: string` + A text output from the model. - The canonical name of the agent that produced this item. + - `Text object { text, type }` - - `created_by: optional string` + A text content. - The identifier of the actor that created the item. + - `text: string` - - `ImageGenerationCall object { id, result, status, 2 more }` + - `type: "text"` - An image generation request made by the model. + - `"text"` - - `id: string` + - `SummaryText object { text, type }` - The unique ID of the image generation call. + A summary text from the model. - - `result: string` + - `text: string` - The generated image encoded in base64. + A summary of the reasoning output from the model so far. - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `type: "summary_text"` - The status of the image generation call. + The type of the object. Always `summary_text`. - - `"in_progress"` + - `"summary_text"` - - `"completed"` + - `ReasoningText object { text, type }` - - `"generating"` + Reasoning text from the model. - - `"failed"` + - `text: string` - - `type: "image_generation_call"` + The reasoning text from the model. - The type of the image generation call. Always `image_generation_call`. + - `type: "reasoning_text"` - - `"image_generation_call"` + The type of the reasoning text. Always `reasoning_text`. - - `agent: optional object { agent_name }` + - `"reasoning_text"` - The agent that produced this item. + - `BetaResponseOutputRefusal object { refusal, type }` - - `agent_name: string` + A refusal from the model. - The canonical name of the agent that produced this item. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `CodeInterpreterCall object { id, code, container_id, 4 more }` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - A tool call to run code. + - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` - - `id: string` + A screenshot of a computer. - The unique ID of the code interpreter tool call. + - `detail: "low" or "high" or "auto" or "original"` - - `code: string` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The code to run, or null if not available. + - `"low"` - - `container_id: string` + - `"high"` - The ID of the container used to run the code. + - `"auto"` - - `outputs: array of object { logs, type } or object { type, url }` + - `"original"` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `file_id: string` - - `Logs object { logs, type }` + The identifier of an uploaded file that contains the screenshot. - The logs output from the code interpreter. + - `image_url: string` - - `logs: string` + The URL of the screenshot image. - The logs output from the code interpreter. + - `type: "computer_screenshot"` - - `type: "logs"` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - The type of the output. Always `logs`. + - `"computer_screenshot"` - - `"logs"` + - `prompt_cache_breakpoint: optional object { mode }` - - `Image object { type, url }` + 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 image output from the code interpreter. + - `mode: "explicit"` - - `type: "image"` + The breakpoint mode. Always `explicit`. - The type of the output. Always `image`. + - `"explicit"` - - `"image"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `url: string` + A file input to the model. - The URL of the image output from the code interpreter. + - `EncryptedContent object { encrypted_content, type }` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `encrypted_content: string` - - `"in_progress"` + Opaque encrypted content. - - `"completed"` + - `type: "encrypted_content"` - - `"incomplete"` + The type of the input item. Always `encrypted_content`. - - `"interpreting"` + - `"encrypted_content"` - - `"failed"` + - `recipient: string` - - `type: "code_interpreter_call"` + The destination agent identity. - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `type: "agent_message"` - - `"code_interpreter_call"` + The type of the item. Always `agent_message`. + + - `"agent_message"` - `agent: optional object { agent_name }` @@ -64290,63 +61847,49 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `LocalShellCall object { id, action, call_id, 3 more }` - - A tool call to run a command on the local shell. - - - `id: string` - - The unique ID of the local shell call. - - - `action: object { command, env, type, 3 more }` - - Execute a shell command on the server. - - - `command: array of string` - - The command to run. - - - `env: map[string]` + - `FunctionCallOutput object { call_id, output, type, 4 more }` - Environment variables to set for the command. + The output of a function tool call. - - `type: "exec"` + - `call_id: string` - The type of the local shell action. Always `exec`. + The unique ID of the function tool call generated by the model. - - `"exec"` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `timeout_ms: optional number` + The output from the function call generated by your code. + Can be a string or an list of output content. - Optional timeout in milliseconds for the command. + - `StringOutput = string` - - `user: optional string` + A string of the output of the function call. - Optional user to run the command as. + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `working_directory: optional string` + Text, image, or file output of the function call. - Optional working directory to run the command in. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `call_id: string` + A text input to the model. - The unique ID of the local shell tool call generated by the model. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `status: "in_progress" or "completed" or "incomplete"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - The status of the local shell call. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `"in_progress"` + A file input to the model. - - `"completed"` + - `type: "function_call_output"` - - `"incomplete"` + The type of the function tool call output. Always `function_call_output`. - - `type: "local_shell_call"` + - `"function_call_output"` - The type of the local shell call. Always `local_shell_call`. + - `id: optional string` - - `"local_shell_call"` + The unique ID of the function tool call output. Populated when this item + is returned via API. - `agent: optional object { agent_name }` @@ -64356,35 +61899,34 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `LocalShellCallOutput object { id, output, type, 2 more }` - - The output of a local shell tool call. + - `caller: optional object { type } or object { caller_id, type }` - - `id: string` + The execution context that produced this tool call. - The unique ID of the local shell tool call generated by the model. + - `Direct object { type }` - - `output: string` + - `type: "direct"` - A JSON string of the output of the local shell tool call. + The caller type. Always `direct`. - - `type: "local_shell_call_output"` + - `"direct"` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `Program object { caller_id, type }` - - `"local_shell_call_output"` + - `caller_id: string` - - `agent: optional object { agent_name }` + The call ID of the program item that produced this tool call. - The agent that produced this item. + - `type: "program"` - - `agent_name: string` + The caller type. Always `program`. - The canonical name of the agent that produced this item. + - `"program"` - `status: optional "in_progress" or "completed" or "incomplete"` - The status of the item. 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"` @@ -64392,73 +61934,39 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `ShellCall object { id, action, call_id, 6 more }` + - `FileSearchCall object { id, queries, status, 3 more }` - A tool call that executes one or more shell commands in a managed environment. + 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 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 shell tool call generated by the model. - - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - - Represents the use of a local environment to perform shell actions. - - - `BetaResponseLocalEnvironment object { type }` - - Represents the use of a local environment to perform shell actions. - - - `type: "local"` - - The environment type. Always `local`. - - - `"local"` - - - `BetaResponseContainerReference object { container_id, type }` - - Represents a container created with /v1/containers. - - - `container_id: string` - - - `type: "container_reference"` + The unique ID of the file search tool call. - The environment type. Always `container_reference`. + - `queries: array of string` - - `"container_reference"` + 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 shell call. One of `in_progress`, `completed`, or `incomplete`. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - `"in_progress"` + - `"searching"` + - `"completed"` - `"incomplete"` - - `type: "shell_call"` + - `"failed"` - The type of the item. Always `shell_call`. + - `type: "file_search_call"` - - `"shell_call"` + The type of the file search tool call. Always `file_search_call`. + + - `"file_search_call"` - `agent: optional object { agent_name }` @@ -64468,217 +61976,173 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - The execution context that produced this tool call. + The results of the file search tool call. - - `Direct object { type }` + - `attributes: optional map[string or number or boolean]` - - `type: "direct"` + 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. - - `"direct"` + - `string` - - `Program object { caller_id, type }` + - `number` - - `caller_id: string` + - `boolean` - The call ID of the program item that produced this tool call. + - `file_id: optional string` - - `type: "program"` + The unique ID of the file. - - `"program"` + - `filename: optional string` - - `created_by: optional string` + The name of the file. - The ID of the entity that created this tool call. + - `score: optional number` - - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` + The relevance score of the file - a value between 0 and 1. - The output of a shell tool call that was emitted. + - `text: optional string` - - `id: string` + The text that was retrieved from the file. - The unique ID of the shell call output. Populated when this item is returned via API. + - `WebSearchCall object { id, action, status, 2 more }` - - `call_id: string` + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - The unique ID of the shell tool call generated by the model. + - `id: string` - - `max_output_length: number` + The unique ID of the web search tool call. - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `output: array of object { outcome, stderr, stdout, created_by }` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - An array of shell call output contents + - `Search object { type, queries, query, sources }` - - `outcome: object { type } or object { exit_code, type }` + Action type "search" - Performs a web search query. - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `type: "search"` - - `Timeout object { type }` + The action type. - Indicates that the shell call exceeded its configured time limit. + - `"search"` - - `type: "timeout"` + - `queries: optional array of string` - The outcome type. Always `timeout`. + The search queries. - - `"timeout"` + - `query: optional string` - - `Exit object { exit_code, type }` + The search query. - Indicates that the shell commands finished and returned an exit code. + - `sources: optional array of object { type, url }` - - `exit_code: number` + The sources used in the search. - Exit code from the shell process. + - `type: "url"` - - `type: "exit"` + The type of source. Always `url`. - The outcome type. Always `exit`. + - `"url"` - - `"exit"` + - `url: string` - - `stderr: string` + The URL of the source. - The standard error output that was captured. + - `OpenPage object { type, url }` - - `stdout: string` + Action type "open_page" - Opens a specific URL from search results. - The standard output that was captured. + - `type: "open_page"` - - `created_by: optional string` + The action type. - The identifier of the actor that created the item. + - `"open_page"` - - `status: "in_progress" or "completed" or "incomplete"` + - `url: optional string` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + The URL opened by the model. - - `"in_progress"` + - `FindInPage object { pattern, type, url }` - - `"completed"` + Action type "find_in_page": Searches for a pattern within a loaded page. - - `"incomplete"` + - `pattern: string` - - `type: "shell_call_output"` + The pattern or text to search for within the page. - The type of the shell call output. Always `shell_call_output`. + - `type: "find_in_page"` - - `"shell_call_output"` + The action type. - - `agent: optional object { agent_name }` + - `"find_in_page"` - The agent that produced this item. + - `url: string` - - `agent_name: string` + The URL of the page searched for the pattern. - The canonical name of the agent that produced this item. + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `caller: optional object { type } or object { caller_id, type }` + The status of the web search tool call. - The execution context that produced this tool call. + - `"in_progress"` - - `Direct object { type }` + - `"searching"` - - `type: "direct"` + - `"completed"` - - `"direct"` + - `"failed"` - - `Program object { caller_id, type }` + - `type: "web_search_call"` - - `caller_id: string` + The type of the web search tool call. Always `web_search_call`. - The call ID of the program item that produced this tool call. + - `"web_search_call"` - - `type: "program"` + - `agent: optional object { agent_name }` - - `"program"` + The agent that produced this item. - - `created_by: optional string` + - `agent_name: string` - The identifier of the actor that created the item. + The canonical name of the agent that produced this item. - - `ApplyPatchCall object { id, call_id, operation, 5 more }` + - `ImageGenerationCall object { id, result, status, 2 more }` - A tool call that applies file diffs by creating, deleting, or updating files. + An image generation request made by the model. - `id: string` - The unique ID of the apply patch tool call. Populated when this item is returned via API. - - - `call_id: string` - - The unique ID of the apply patch tool call generated by the model. - - - `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. - - - `CreateFile object { diff, path, type }` - - Instruction describing how to create a file via the apply_patch tool. - - - `diff: string` - - Diff to apply. - - - `path: string` - - Path of the file to create. - - - `type: "create_file"` - - Create a new file with the provided diff. - - - `"create_file"` - - - `DeleteFile object { path, type }` - - Instruction describing how to delete a file via the apply_patch tool. - - - `path: string` - - Path of the file to delete. - - - `type: "delete_file"` - - Delete the specified file. - - - `"delete_file"` - - - `UpdateFile object { diff, path, type }` - - Instruction describing how to update a file via the apply_patch tool. - - - `diff: string` - - Diff to apply. - - - `path: string` - - Path of the file to update. - - - `type: "update_file"` + The unique ID of the image generation call. - Update an existing file with the provided diff. + - `result: string` - - `"update_file"` + The generated image encoded in base64. - - `status: "in_progress" or "completed"` + - `status: "in_progress" or "completed" or "generating" or "failed"` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The status of the image generation call. - `"in_progress"` - `"completed"` - - `type: "apply_patch_call"` + - `"generating"` - The type of the item. Always `apply_patch_call`. + - `"failed"` - - `"apply_patch_call"` + - `type: "image_generation_call"` + + The type of the image generation call. Always `image_generation_call`. + + - `"image_generation_call"` - `agent: optional object { agent_name }` @@ -64688,296 +62152,287 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `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` + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - The call ID of the program item that produced this tool call. + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - - `type: "program"` + - `id: string` - - `"program"` + The unique ID of the computer call. - - `created_by: optional string` + - `call_id: string` - The ID of the entity that created this tool call. + An identifier used when responding to the tool call with output. - - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` + - `pending_safety_checks: array of object { id, code, message }` - The output emitted by an apply patch tool call. + The pending safety checks for the computer 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. + The ID of the pending safety check. - - `status: "completed" or "failed"` + - `code: optional string` - The status of the apply patch tool call output. One of `completed` or `failed`. + The type of the pending safety check. - - `"completed"` + - `message: optional string` - - `"failed"` + Details about the pending safety check. - - `type: "apply_patch_call_output"` + - `status: "in_progress" or "completed" or "incomplete"` - The type of the item. Always `apply_patch_call_output`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"apply_patch_call_output"` + - `"in_progress"` - - `agent: optional object { agent_name }` + - `"completed"` - The agent that produced this item. + - `"incomplete"` - - `agent_name: string` + - `type: "computer_call"` - The canonical name of the agent that produced this item. + The type of the computer call. Always `computer_call`. - - `caller: optional object { type } or object { caller_id, type }` + - `"computer_call"` - The execution context that produced this tool call. + - `action: optional BetaComputerAction` - - `Direct object { type }` + A click action. - - `type: "direct"` + - `Click object { button, type, x, 2 more }` - - `"direct"` + A click action. - - `Program object { caller_id, type }` + - `button: "left" or "right" or "wheel" or 2 more` - - `caller_id: string` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - The call ID of the program item that produced this tool call. + - `"left"` - - `type: "program"` + - `"right"` - - `"program"` + - `"wheel"` - - `created_by: optional string` + - `"back"` - The ID of the entity that created this tool call output. + - `"forward"` - - `output: optional string` + - `type: "click"` - Optional textual output returned by the apply patch tool. + Specifies the event type. For a click action, this property is always `click`. - - `McpCall object { id, arguments, name, 7 more }` + - `"click"` - An invocation of a tool on an MCP server. + - `x: number` - - `id: string` + The x-coordinate where the click occurred. - The unique ID of the tool call. + - `y: number` - - `arguments: string` + The y-coordinate where the click occurred. - A JSON string of the arguments passed to the tool. + - `keys: optional array of string` - - `name: string` + The keys being held while clicking. - The name of the tool that was run. + - `DoubleClick object { keys, type, x, y }` - - `server_label: string` + A double click action. - The label of the MCP server running the tool. + - `keys: array of string` - - `type: "mcp_call"` + The keys being held while double-clicking. - The type of the item. Always `mcp_call`. + - `type: "double_click"` - - `"mcp_call"` + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `agent: optional object { agent_name }` + - `"double_click"` - The agent that produced this item. + - `x: number` - - `agent_name: string` + The x-coordinate where the double click occurred. - The canonical name of the agent that produced this item. + - `y: number` - - `approval_request_id: optional string` + The y-coordinate where the double click occurred. - 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. + - `Drag object { path, type, keys }` - - `error: optional string` + A drag action. - The error from the tool call, if any. + - `path: array of object { x, y }` - - `output: optional string` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - The output from the tool call. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `x: number` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The x-coordinate. - - `"in_progress"` + - `y: number` - - `"completed"` + The y-coordinate. - - `"incomplete"` + - `type: "drag"` - - `"calling"` + Specifies the event type. For a drag action, this property is always set to `drag`. - - `"failed"` + - `"drag"` - - `McpListTools object { id, server_label, tools, 3 more }` + - `keys: optional array of string` - A list of tools available on an MCP server. + The keys being held while dragging the mouse. - - `id: string` + - `Keypress object { keys, type }` - The unique ID of the list. + A collection of keypresses the model would like to perform. - - `server_label: string` + - `keys: array of string` - The label of the MCP server. + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `tools: array of object { input_schema, name, annotations, description }` + - `type: "keypress"` - The tools available on the server. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `input_schema: unknown` + - `"keypress"` - The JSON schema describing the tool's input. + - `Move object { type, x, y, keys }` - - `name: string` + A mouse move action. - The name of the tool. + - `type: "move"` - - `annotations: optional unknown` + Specifies the event type. For a move action, this property is always set to `move`. - Additional annotations about the tool. + - `"move"` - - `description: optional string` + - `x: number` - The description of the tool. + The x-coordinate to move to. - - `type: "mcp_list_tools"` + - `y: number` - The type of the item. Always `mcp_list_tools`. + The y-coordinate to move to. - - `"mcp_list_tools"` + - `keys: optional array of string` - - `agent: optional object { agent_name }` + The keys being held while moving the mouse. - The agent that produced this item. + - `Screenshot object { type }` - - `agent_name: string` + A screenshot action. - The canonical name of the agent that produced this item. + - `type: "screenshot"` - - `error: optional string` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - Error message if the server could not list tools. + - `"screenshot"` - - `McpApprovalRequest object { id, arguments, name, 3 more }` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - A request for human approval of a tool invocation. + A scroll action. - - `id: string` + - `scroll_x: number` - The unique ID of the approval request. + The horizontal scroll distance. - - `arguments: string` + - `scroll_y: number` - A JSON string of arguments for the tool. + The vertical scroll distance. - - `name: string` + - `type: "scroll"` - The name of the tool to run. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `server_label: string` + - `"scroll"` - The label of the MCP server making the request. + - `x: number` - - `type: "mcp_approval_request"` + The x-coordinate where the scroll occurred. - The type of the item. Always `mcp_approval_request`. + - `y: number` - - `"mcp_approval_request"` + The y-coordinate where the scroll occurred. - - `agent: optional object { agent_name }` + - `keys: optional array of string` - The agent that produced this item. + The keys being held while scrolling. - - `agent_name: string` + - `Type object { text, type }` - The canonical name of the agent that produced this item. + An action to type in text. - - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` + - `text: string` - A response to an MCP approval request. + The text to type. - - `id: string` + - `type: "type"` - The unique ID of the approval response + Specifies the event type. For a type action, this property is always set to `type`. - - `approval_request_id: string` + - `"type"` - The ID of the approval request being answered. + - `Wait object { type }` - - `approve: boolean` + A wait action. - Whether the request was approved. + - `type: "wait"` - - `type: "mcp_approval_response"` + Specifies the event type. For a wait action, this property is always set to `wait`. - The type of the item. Always `mcp_approval_response`. + - `"wait"` - - `"mcp_approval_response"` + - `actions: optional BetaComputerActionList` - - `agent: optional object { agent_name }` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - The agent that produced this item. + - `Click object { button, type, x, 2 more }` - - `agent_name: string` + A click action. - The canonical name of the agent that produced this item. + - `DoubleClick object { keys, type, x, y }` - - `reason: optional string` + A double click action. - Optional reason for the decision. + - `Drag object { path, type, keys }` - - `CustomToolCall object { call_id, input, name, 5 more }` + A drag action. - A call to a custom tool created by the model. + - `Keypress object { keys, type }` - - `call_id: string` + A collection of keypresses the model would like to perform. - An identifier used to map this custom tool call to a tool call output. + - `Move object { type, x, y, keys }` - - `input: string` + A mouse move action. - The input for the custom tool call generated by the model. + - `Screenshot object { type }` - - `name: string` + A screenshot action. - The name of the custom tool being called. + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `type: "custom_tool_call"` + A scroll action. - The type of the custom tool call. Always `custom_tool_call`. + - `Type object { text, type }` - - `"custom_tool_call"` + An action to type in text. - - `id: optional string` + - `Wait object { type }` - The unique ID of the custom tool call in the OpenAI platform. + A wait action. - `agent: optional object { agent_name }` @@ -64987,2119 +62442,1948 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `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, 5 more }` + - `ComputerCallOutput object { id, call_id, output, 5 more }` - `id: string` - The unique ID of the custom tool call output item. + The unique ID of the computer call tool output. - `call_id: string` - The call ID, used to map this custom tool call output to a custom tool call. - - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - 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. + The ID of the computer tool call that produced the output. - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `output: BetaResponseComputerToolCallOutputScreenshot` - Text, image, or file output of the custom tool call. + A computer screenshot image used with the computer use tool. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `type: "computer_screenshot"` - A text input to the model. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `"computer_screenshot"` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `file_id: optional string` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + The identifier of an uploaded file that contains the screenshot. - A file input to the model. + - `image_url: optional string` - - `status: "in_progress" or "completed" or "incomplete"` + The URL of the screenshot image. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - - `"in_progress"` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - `"completed"` - - `"incomplete"` - - - `type: "custom_tool_call_output"` - - The type of the custom tool call output. Always `custom_tool_call_output`. - - - `"custom_tool_call_output"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `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 }` + - `"incomplete"` - - `caller_id: string` + - `"failed"` - The call ID of the program item that produced this tool call. + - `"in_progress"` - - `type: "program"` + - `type: "computer_call_output"` - The caller type. Always `program`. + The type of the computer tool call output. Always `computer_call_output`. - - `"program"` + - `"computer_call_output"` - - `created_by: optional string` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - The identifier of the actor that created the item. + The safety checks reported by the API that have been acknowledged by the + developer. - - `parallel_tool_calls: boolean` + - `id: string` - Whether to allow the model to run tool calls in parallel. + The ID of the pending safety check. - - `temperature: number` + - `code: optional 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 type of the pending safety check. - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + - `message: optional 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. + Details about the pending safety check. - - `BetaToolChoiceOptions = "none" or "auto" or "required"` + - `agent: optional object { agent_name }` - Controls which (if any) tool is called by the model. + The agent that produced this item. - `none` means the model will not call any tool and instead generates a message. + - `agent_name: string` - `auto` means the model can pick between generating a message or calling one or - more tools. + The canonical name of the agent that produced this item. - `required` means the model must call one or more tools. + - `created_by: optional string` - - `"none"` + The identifier of the actor that created the item. - - `"auto"` + - `Reasoning object { id, summary, type, 4 more }` - - `"required"` + 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). - - `BetaToolChoiceAllowed object { mode, tools, type }` + - `id: string` - Constrains the tools available to the model to a pre-defined set. + The unique identifier of the reasoning content. - - `mode: "auto" or "required"` + - `summary: array of object { text, type }` - Constrains the tools available to the model to a pre-defined set. + Reasoning summary content. - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `text: string` - `required` requires the model to call one or more of the allowed tools. + A summary of the reasoning output from the model so far. - - `"auto"` + - `type: "summary_text"` - - `"required"` + The type of the object. Always `summary_text`. - - `tools: array of map[unknown]` + - `"summary_text"` - A list of tool definitions that the model should be allowed to call. + - `type: "reasoning"` - For the Responses API, the list of tool definitions might look like: + The type of the object. Always `reasoning`. - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `"reasoning"` - - `type: "allowed_tools"` + - `agent: optional object { agent_name }` - Allowed tool configuration type. Always `allowed_tools`. + The agent that produced this item. - - `"allowed_tools"` + - `agent_name: string` - - `BetaToolChoiceTypes object { type }` + The canonical name of the agent that produced this item. - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](/docs/guides/tools). + - `content: optional array of object { text, type }` - - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + Reasoning text content. - The type of hosted tool the model should to use. Learn more about - [built-in tools](/docs/guides/tools). + - `text: string` - Allowed values are: + The reasoning text from the model. - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `type: "reasoning_text"` - - `"file_search"` + The type of the reasoning text. Always `reasoning_text`. - - `"web_search_preview"` + - `"reasoning_text"` - - `"computer"` + - `encrypted_content: optional string` - - `"computer_use_preview"` + 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. - - `"computer_use"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"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. - - `"image_generation"` + - `"in_progress"` - - `"code_interpreter"` + - `"completed"` - - `BetaToolChoiceFunction object { name, type }` + - `"incomplete"` - Use this option to force the model to call a specific function. + - `Compaction object { id, encrypted_content, type, 2 more }` - - `name: string` + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - The name of the function to call. + - `id: string` - - `type: "function"` + The unique ID of the compaction item. - For function calling, the type is always `function`. + - `encrypted_content: string` - - `"function"` + The encrypted content that was produced by compaction. - - `BetaToolChoiceMcp object { server_label, type, name }` + - `type: "compaction"` - Use this option to force the model to call a specific tool on a remote MCP server. + The type of the item. Always `compaction`. - - `server_label: string` + - `"compaction"` - The label of the MCP server to use. + - `agent: optional object { agent_name }` - - `type: "mcp"` + The agent that produced this item. - For MCP tools, the type is always `mcp`. + - `agent_name: string` - - `"mcp"` + The canonical name of the agent that produced this item. - - `name: optional string` + - `created_by: optional string` - The name of the tool to call on the server. + The identifier of the actor that created the item. - - `BetaToolChoiceCustom object { name, type }` + - `CodeInterpreterCall object { id, code, container_id, 4 more }` - Use this option to force the model to call a specific custom tool. + A tool call to run code. - - `name: string` + - `id: string` - The name of the custom tool to call. + The unique ID of the code interpreter tool call. - - `type: "custom"` + - `code: string` - For custom tool calling, the type is always `custom`. + The code to run, or null if not available. - - `"custom"` + - `container_id: string` - - `BetaSpecificProgrammaticToolCallingParam object { type }` + The ID of the container used to run the code. - - `type: "programmatic_tool_calling"` + - `outputs: array of object { logs, type } or object { type, url }` - The tool to call. Always `programmatic_tool_calling`. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `"programmatic_tool_calling"` + - `Logs object { logs, type }` - - `BetaToolChoiceApplyPatch object { type }` + The logs output from the code interpreter. - Forces the model to call the apply_patch tool when executing a tool call. + - `logs: string` - - `type: "apply_patch"` + The logs output from the code interpreter. - The tool to call. Always `apply_patch`. + - `type: "logs"` - - `"apply_patch"` + The type of the output. Always `logs`. - - `BetaToolChoiceShell object { type }` + - `"logs"` - Forces the model to call the shell tool when a tool call is required. + - `Image object { type, url }` - - `type: "shell"` + The image output from the code interpreter. - The tool to call. Always `shell`. + - `type: "image"` - - `"shell"` + The type of the output. Always `image`. - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + - `"image"` - 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. + - `url: string` - We support the following categories of tools: + The URL of the image output from the code interpreter. - - **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: "in_progress" or "completed" or "incomplete" or 2 more` - - `Function object { name, parameters, strict, 5 more }` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `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). + - `"in_progress"` - - `name: string` + - `"completed"` - The name of the function to call. + - `"incomplete"` - - `parameters: map[unknown]` + - `"interpreting"` - A JSON schema object describing the parameters of the function. + - `"failed"` - - `strict: boolean` + - `type: "code_interpreter_call"` - Whether strict parameter validation is enforced for this function tool. + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `type: "function"` + - `"code_interpreter_call"` - The type of the function tool. Always `function`. + - `agent: optional object { agent_name }` - - `"function"` + The agent that produced this item. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `agent_name: string` - The tool invocation context(s). + The canonical name of the agent that produced this item. - - `"direct"` + - `LocalShellCall object { id, action, call_id, 3 more }` - - `"programmatic"` + A tool call to run a command on the local shell. - - `defer_loading: optional boolean` + - `id: string` - Whether this function is deferred and loaded via tool search. + The unique ID of the local shell call. - - `description: optional string` + - `action: object { command, env, type, 3 more }` - A description of the function. Used by the model to determine whether or not to call the function. + Execute a shell command on the server. - - `output_schema: optional map[unknown]` + - `command: array of string` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The command to run. - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `env: map[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). + Environment variables to set for the command. - - `type: "file_search"` + - `type: "exec"` - The type of the file search tool. Always `file_search`. + The type of the local shell action. Always `exec`. - - `"file_search"` + - `"exec"` - - `vector_store_ids: array of string` + - `timeout_ms: optional number` - The IDs of the vector stores to search. + Optional timeout in milliseconds for the command. - - `filters: optional object { key, type, value } or object { filters, type }` + - `user: optional string` - A filter to apply. + Optional user to run the command as. - - `ComparisonFilter object { key, type, value }` + - `working_directory: optional string` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + Optional working directory to run the command in. - - `key: string` + - `call_id: string` - The key to compare against the value. + The unique ID of the local shell tool call generated by the model. - - `type: "eq" or "ne" or "gt" or 5 more` + - `status: "in_progress" or "completed" or "incomplete"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The status of the local shell 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 + - `"in_progress"` - - `"eq"` + - `"completed"` - - `"ne"` + - `"incomplete"` - - `"gt"` + - `type: "local_shell_call"` - - `"gte"` + The type of the local shell call. Always `local_shell_call`. - - `"lt"` + - `"local_shell_call"` - - `"lte"` + - `agent: optional object { agent_name }` - - `"in"` + The agent that produced this item. - - `"nin"` + - `agent_name: string` - - `value: string or number or boolean or array of string or number` + The canonical name of the agent that produced this item. - The value to compare against the attribute key; supports string, number, or boolean types. + - `LocalShellCallOutput object { id, output, type, 2 more }` - - `string` + The output of a local shell tool call. - - `number` + - `id: string` - - `boolean` + The unique ID of the local shell tool call generated by the model. - - `array of string or number` + - `output: string` - - `string` + A JSON string of the output of the local shell tool call. - - `number` + - `type: "local_shell_call_output"` - - `CompoundFilter object { filters, type }` + The type of the local shell tool call output. Always `local_shell_call_output`. - Combine multiple filters using `and` or `or`. + - `"local_shell_call_output"` - - `filters: array of object { key, type, value } or unknown` + - `agent: optional object { agent_name }` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + The agent that produced this item. - - `ComparisonFilter object { key, type, value }` + - `agent_name: string` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The canonical name of the agent that produced this item. - - `key: string` + - `status: optional "in_progress" or "completed" or "incomplete"` - The key to compare against the value. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `type: "eq" or "ne" or "gt" or 5 more` + - `"in_progress"` - 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 + - `"incomplete"` - - `"eq"` + - `ShellCall object { id, action, call_id, 6 more }` - - `"ne"` + A tool call that executes one or more shell commands in a managed environment. - - `"gt"` + - `id: string` - - `"gte"` + The unique ID of the shell tool call. Populated when this item is returned via API. - - `"lt"` + - `action: object { commands, max_output_length, timeout_ms }` - - `"lte"` + The shell commands and limits that describe how to run the tool call. - - `"in"` + - `commands: array of string` - - `"nin"` + - `max_output_length: number` - - `value: string or number or boolean or array of string or number` + Optional maximum number of characters to return from each command. - The value to compare against the attribute key; supports string, number, or boolean types. + - `timeout_ms: number` - - `string` + Optional timeout in milliseconds for the commands. - - `number` + - `call_id: string` - - `boolean` + The unique ID of the shell tool call generated by the model. - - `array of string or number` + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - - `string` + Represents the use of a local environment to perform shell actions. - - `number` + - `BetaResponseLocalEnvironment object { type }` - - `unknown` + Represents the use of a local environment to perform shell actions. - - `type: "and" or "or"` + - `type: "local"` - Type of operation: `and` or `or`. + The environment type. Always `local`. - - `"and"` + - `"local"` - - `"or"` + - `BetaResponseContainerReference object { container_id, type }` - - `max_num_results: optional number` + Represents a container created with /v1/containers. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `container_id: string` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `type: "container_reference"` - Ranking options for search. + The environment type. Always `container_reference`. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `"container_reference"` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `status: "in_progress" or "completed" or "incomplete"` - - `embedding_weight: number` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - The weight of the embedding in the reciprocal ranking fusion. + - `"in_progress"` - - `text_weight: number` + - `"completed"` - The weight of the text in the reciprocal ranking fusion. + - `"incomplete"` - - `ranker: optional "auto" or "default-2024-11-15"` + - `type: "shell_call"` - The ranker to use for the file search. + The type of the item. Always `shell_call`. - - `"auto"` + - `"shell_call"` - - `"default-2024-11-15"` + - `agent: optional object { agent_name }` - - `score_threshold: optional number` + The agent that produced this item. - 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. + - `agent_name: string` - - `Computer object { type }` + The canonical name of the agent that produced this item. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `caller: optional object { type } or object { caller_id, type }` - - `type: "computer"` + The execution context that produced this tool call. - The type of the computer tool. Always `computer`. + - `Direct object { type }` - - `"computer"` + - `type: "direct"` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `"direct"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `Program object { caller_id, type }` - - `display_height: number` + - `caller_id: string` - The height of the computer display. + The call ID of the program item that produced this tool call. - - `display_width: number` + - `type: "program"` - The width of the computer display. + - `"program"` - - `environment: "windows" or "mac" or "linux" or 2 more` + - `created_by: optional string` - The type of computer environment to control. + The ID of the entity that created this tool call. - - `"windows"` + - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` - - `"mac"` + The output of a shell tool call that was emitted. - - `"linux"` + - `id: string` - - `"ubuntu"` + The unique ID of the shell call output. Populated when this item is returned via API. - - `"browser"` + - `call_id: string` - - `type: "computer_use_preview"` + The unique ID of the shell tool call generated by the model. - The type of the computer use tool. Always `computer_use_preview`. + - `max_output_length: number` - - `"computer_use_preview"` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `WebSearch object { type, filters, search_context_size, user_location }` + - `output: array of object { outcome, stderr, stdout, created_by }` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + An array of shell call output contents - - `type: "web_search" or "web_search_2025_08_26"` + - `outcome: object { type } or object { exit_code, type }` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `"web_search"` + - `Timeout object { type }` - - `"web_search_2025_08_26"` + Indicates that the shell call exceeded its configured time limit. - - `filters: optional object { allowed_domains }` + - `type: "timeout"` - Filters for the search. + The outcome type. Always `timeout`. - - `allowed_domains: optional array of string` + - `"timeout"` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `Exit object { exit_code, type }` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + Indicates that the shell commands finished and returned an exit code. - - `search_context_size: optional "low" or "medium" or "high"` + - `exit_code: number` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + Exit code from the shell process. - - `"low"` + - `type: "exit"` - - `"medium"` + The outcome type. Always `exit`. - - `"high"` + - `"exit"` - - `user_location: optional object { city, country, region, 2 more }` + - `stderr: string` - The approximate location of the user. + The standard error output that was captured. - - `city: optional string` + - `stdout: string` - Free text input for the city of the user, e.g. `San Francisco`. + The standard output that was captured. - - `country: optional string` + - `created_by: optional string` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The identifier of the actor that created the item. - - `region: optional string` + - `status: "in_progress" or "completed" or "incomplete"` - Free text input for the region of the user, e.g. `California`. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `timezone: optional string` + - `"in_progress"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"completed"` - - `type: optional "approximate"` + - `"incomplete"` - The type of location approximation. Always `approximate`. + - `type: "shell_call_output"` - - `"approximate"` + The type of the shell call output. Always `shell_call_output`. - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `"shell_call_output"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + - `agent: optional object { agent_name }` - - `server_label: string` + The agent that produced this item. - A label for this MCP server, used to identify it in tool calls. + - `agent_name: string` - - `type: "mcp"` + The canonical name of the agent that produced this item. - The type of the MCP tool. Always `mcp`. + - `caller: optional object { type } or object { caller_id, type }` - - `"mcp"` + The execution context that produced this tool call. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `Direct object { type }` - The tool invocation context(s). + - `type: "direct"` - `"direct"` - - `"programmatic"` + - `Program object { caller_id, type }` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `caller_id: string` - List of allowed tool names or a filter object. + The call ID of the program item that produced this tool call. - - `McpAllowedTools = array of string` + - `type: "program"` - A string array of allowed tool names + - `"program"` - - `McpToolFilter object { read_only, tool_names }` + - `created_by: optional string` - A filter object to specify which tools are allowed. + The identifier of the actor that created the item. - - `read_only: optional boolean` + - `ApplyPatchCall object { id, call_id, operation, 5 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 tool call that applies file diffs by creating, deleting, or updating files. - - `tool_names: optional array of string` + - `id: string` - List of allowed tool names. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `authorization: optional string` + - `call_id: string` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + The unique ID of the apply patch tool call generated by the model. - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - 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). + One of the create_file, delete_file, or update_file operations applied via apply_patch. - Currently supported `connector_id` values are: + - `CreateFile object { diff, path, type }` - - 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` + Instruction describing how to create a file via the apply_patch tool. - - `"connector_dropbox"` + - `diff: string` - - `"connector_gmail"` + Diff to apply. - - `"connector_googlecalendar"` + - `path: string` - - `"connector_googledrive"` + Path of the file to create. - - `"connector_microsoftteams"` + - `type: "create_file"` - - `"connector_outlookcalendar"` + Create a new file with the provided diff. - - `"connector_outlookemail"` + - `"create_file"` - - `"connector_sharepoint"` + - `DeleteFile object { path, type }` - - `defer_loading: optional boolean` + Instruction describing how to delete a file via the apply_patch tool. - Whether this MCP tool is deferred and discovered via tool search. + - `path: string` - - `headers: optional map[string]` + Path of the file to delete. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `type: "delete_file"` - - `require_approval: optional object { always, never } or "always" or "never"` + Delete the specified file. - Specify which of the MCP server's tools require approval. + - `"delete_file"` - - `McpToolApprovalFilter object { always, never }` + - `UpdateFile 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 describing how to update a file via the apply_patch tool. - - `always: optional object { read_only, tool_names }` + - `diff: string` - A filter object to specify which tools are allowed. + Diff to apply. - - `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 update. - - `tool_names: optional array of string` + - `type: "update_file"` - List of allowed tool names. + Update an existing file with the provided diff. - - `never: optional object { read_only, tool_names }` + - `"update_file"` - A filter object to specify which tools are allowed. + - `status: "in_progress" or "completed"` - - `read_only: optional boolean` + The status of the apply patch tool call. One of `in_progress` or `completed`. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `"in_progress"` - - `tool_names: optional array of string` + - `"completed"` - List of allowed tool names. + - `type: "apply_patch_call"` - - `McpToolApprovalSetting = "always" or "never"` + The type of the item. Always `apply_patch_call`. - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `"apply_patch_call"` - - `"always"` + - `agent: optional object { agent_name }` - - `"never"` + The agent that produced this item. - - `server_description: optional string` + - `agent_name: string` - Optional description of the MCP server, used to provide more context. + The canonical name of the agent that produced this item. - - `server_url: optional string` + - `caller: optional object { type } or object { caller_id, type }` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + The execution context that produced this tool call. - - `tunnel_id: optional string` + - `Direct object { type }` - 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: "direct"` - - `CodeInterpreter object { container, type, allowed_callers }` + - `"direct"` - A tool that runs Python code to help generate a response to a prompt. + - `Program object { caller_id, type }` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `caller_id: string` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + The call ID of the program item that produced this tool call. - - `string` + - `type: "program"` - The container ID. + - `"program"` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `created_by: optional string` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + The ID of the entity that created this tool call. - - `type: "auto"` + - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` - Always `auto`. + The output emitted by an apply patch tool call. - - `"auto"` + - `id: string` - - `file_ids: optional array of string` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - An optional list of uploaded files to make available to your code. + - `call_id: string` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + The unique ID of the apply patch tool call generated by the model. - The memory limit for the code interpreter container. + - `status: "completed" or "failed"` - - `"1g"` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `"4g"` + - `"completed"` - - `"16g"` + - `"failed"` - - `"64g"` + - `type: "apply_patch_call_output"` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + The type of the item. Always `apply_patch_call_output`. - Network access policy for the container. + - `"apply_patch_call_output"` - - `BetaContainerNetworkPolicyDisabled object { type }` + - `agent: optional object { agent_name }` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + The agent that produced this item. - - `type: "code_interpreter"` + - `agent_name: string` - The type of the code interpreter tool. Always `code_interpreter`. + The canonical name of the agent that produced this item. - - `"code_interpreter"` + - `caller: optional object { type } or object { caller_id, type }` - - `allowed_callers: optional array of "direct" or "programmatic"` + The execution context that produced this tool call. - The tool invocation context(s). + - `Direct object { type }` + + - `type: "direct"` - `"direct"` - - `"programmatic"` + - `Program object { caller_id, type }` - - `ProgrammaticToolCalling object { type }` + - `caller_id: string` - - `type: "programmatic_tool_calling"` + The call ID of the program item that produced this tool call. - The type of the tool. Always `programmatic_tool_calling`. + - `type: "program"` - - `"programmatic_tool_calling"` + - `"program"` - - `ImageGeneration object { type, action, background, 9 more }` + - `created_by: optional string` - A tool that generates images using the GPT image models. + The ID of the entity that created this tool call output. - - `type: "image_generation"` + - `output: optional string` - The type of the image generation tool. Always `image_generation`. + Optional textual output returned by the apply patch tool. - - `"image_generation"` + - `McpListTools object { id, server_label, tools, 3 more }` - - `action: optional "generate" or "edit" or "auto"` + A list of tools available on an MCP server. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `id: string` - - `"generate"` + The unique ID of the list. - - `"edit"` + - `server_label: string` - - `"auto"` + The label of the MCP server. - - `background: optional "transparent" or "opaque" or "auto"` + - `tools: array of object { input_schema, name, annotations, description }` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + The tools available on the server. - - `"transparent"` + - `input_schema: unknown` - - `"opaque"` + The JSON schema describing the tool's input. - - `"auto"` + - `name: string` - - `input_fidelity: optional "high" or "low"` + The name of the tool. - 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`. + - `annotations: optional unknown` - - `"high"` + Additional annotations about the tool. - - `"low"` + - `description: optional string` - - `input_image_mask: optional object { file_id, image_url }` + The description of the tool. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `type: "mcp_list_tools"` - - `file_id: optional string` + The type of the item. Always `mcp_list_tools`. - File ID for the mask image. + - `"mcp_list_tools"` - - `image_url: optional string` + - `agent: optional object { agent_name }` - Base64-encoded mask image. + The agent that produced this item. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `agent_name: string` - The image generation model to use. Default: `gpt-image-1`. + The canonical name of the agent that produced this item. - - `string` + - `error: optional string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + Error message if the server could not list tools. - The image generation model to use. Default: `gpt-image-1`. + - `McpApprovalRequest object { id, arguments, name, 3 more }` - - `"gpt-image-1"` + A request for human approval of a tool invocation. - - `"gpt-image-1-mini"` + - `id: string` - - `"gpt-image-1.5"` + The unique ID of the approval request. - - `moderation: optional "auto" or "low"` + - `arguments: string` - Moderation level for the generated image. Default: `auto`. + A JSON string of arguments for the tool. - - `"auto"` + - `name: string` - - `"low"` + The name of the tool to run. - - `output_compression: optional number` + - `server_label: string` - Compression level for the output image. Default: 100. + The label of the MCP server making the request. - - `output_format: optional "png" or "webp" or "jpeg"` + - `type: "mcp_approval_request"` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + The type of the item. Always `mcp_approval_request`. - - `"png"` + - `"mcp_approval_request"` - - `"webp"` + - `agent: optional object { agent_name }` - - `"jpeg"` + The agent that produced this item. - - `partial_images: optional number` + - `agent_name: string` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The canonical name of the agent that produced this item. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + A response to an MCP approval request. - - `"low"` + - `id: string` - - `"medium"` + The unique ID of the approval response - - `"high"` + - `approval_request_id: string` - - `"auto"` + The ID of the approval request being answered. - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `approve: boolean` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + Whether the request was approved. - - `string` + - `type: "mcp_approval_response"` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The type of the item. Always `mcp_approval_response`. - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `"mcp_approval_response"` - - `"1024x1024"` + - `agent: optional object { agent_name }` - - `"1024x1536"` + The agent that produced this item. - - `"1536x1024"` + - `agent_name: string` - - `"auto"` + The canonical name of the agent that produced this item. - - `LocalShell object { type }` + - `reason: optional string` - A tool that allows the model to execute shell commands in a local environment. + Optional reason for the decision. - - `type: "local_shell"` + - `McpCall object { id, arguments, name, 7 more }` - The type of the local shell tool. Always `local_shell`. + An invocation of a tool on an MCP server. - - `"local_shell"` + - `id: string` - - `Shell object { type, allowed_callers, environment }` + The unique ID of the tool call. - A tool that allows the model to execute shell commands. + - `arguments: string` - - `type: "shell"` + A JSON string of the arguments passed to the tool. - The type of the shell tool. Always `shell`. + - `name: string` - - `"shell"` + The name of the tool that was run. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `server_label: string` - The tool invocation context(s). + The label of the MCP server running the tool. - - `"direct"` + - `type: "mcp_call"` - - `"programmatic"` + The type of the item. Always `mcp_call`. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `"mcp_call"` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `agent: optional object { agent_name }` - - `BetaLocalEnvironment object { type, skills }` + The agent that produced this item. - - `BetaContainerReference object { container_id, type }` + - `agent_name: string` - - `Custom object { name, type, allowed_callers, 3 more }` + The canonical name of the agent that produced this item. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `approval_request_id: optional string` - - `name: 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 name of the custom tool, used to identify it in tool calls. + - `error: optional string` - - `type: "custom"` + The error from the tool call, if any. - The type of the custom tool. Always `custom`. + - `output: optional string` - - `"custom"` + The output from the tool call. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - The tool invocation context(s). + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `"direct"` + - `"in_progress"` - - `"programmatic"` + - `"completed"` - - `defer_loading: optional boolean` + - `"incomplete"` - Whether this tool should be deferred and discovered via tool search. + - `"calling"` - - `description: optional string` + - `"failed"` - Optional description of the custom tool, used to provide more context. + - `CustomToolCall object { call_id, input, name, 5 more }` - - `format: optional object { type } or object { definition, syntax, type }` + A call to a custom tool created by the model. - The input format for the custom tool. Default is unconstrained text. + - `call_id: string` - - `Text object { type }` + An identifier used to map this custom tool call to a tool call output. - Unconstrained free-form text. + - `input: string` - - `type: "text"` + The input for the custom tool call generated by the model. - Unconstrained text format. Always `text`. + - `name: string` - - `"text"` + The name of the custom tool being called. - - `Grammar object { definition, syntax, type }` + - `type: "custom_tool_call"` - A grammar defined by the user. + The type of the custom tool call. Always `custom_tool_call`. - - `definition: string` + - `"custom_tool_call"` - The grammar definition. + - `id: optional string` - - `syntax: "lark" or "regex"` + The unique ID of the custom tool call in the OpenAI platform. - The syntax of the grammar definition. One of `lark` or `regex`. + - `agent: optional object { agent_name }` - - `"lark"` + The agent that produced this item. - - `"regex"` + - `agent_name: string` - - `type: "grammar"` + The canonical name of the agent that produced this item. - Grammar format. Always `grammar`. + - `caller: optional object { type } or object { caller_id, type }` - - `"grammar"` + The execution context that produced this tool call. - - `Namespace object { description, name, tools, type }` + - `Direct object { type }` - Groups function/custom tools under a shared namespace. + - `type: "direct"` - - `description: string` + - `"direct"` - A description of the namespace shown to the model. + - `Program object { caller_id, type }` - - `name: string` + - `caller_id: string` - The namespace name used in tool calls (for example, `crm`). + The call ID of the program item that produced this tool call. - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `type: "program"` - The function/custom tools available inside this namespace. + - `"program"` - - `Function object { name, type, allowed_callers, 5 more }` + - `namespace: optional string` - - `name: string` + The namespace of the custom tool being called. - - `type: "function"` + - `CustomToolCallOutput object { call_id, output, type, 3 more }` - - `"function"` + The output of a custom tool call from your code, being sent back to the model. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `call_id: string` - The tool invocation context(s). + The call ID, used to map this custom tool call output to a custom tool call. - - `"direct"` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `"programmatic"` + - `StringOutput = string` - - `defer_loading: optional boolean` + A string of the output of the custom tool call. - Whether this function should be deferred and discovered via tool search. + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `description: optional string` + Text, image, or file output of the custom tool call. - - `output_schema: optional map[unknown]` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + A text input to the model. - - `parameters: optional unknown` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `strict: optional boolean` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - 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. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `Custom object { name, type, allowed_callers, 3 more }` + A file 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) + - `type: "custom_tool_call_output"` - - `name: string` + The type of the custom tool call output. Always `custom_tool_call_output`. - The name of the custom tool, used to identify it in tool calls. + - `"custom_tool_call_output"` - - `type: "custom"` + - `id: optional string` - The type of the custom tool. Always `custom`. + The unique ID of the custom tool call output in the OpenAI platform. - - `"custom"` + - `agent: optional object { agent_name }` - - `allowed_callers: optional array of "direct" or "programmatic"` + The agent that produced this item. - The tool invocation context(s). + - `agent_name: string` - - `"direct"` + The canonical name of the agent that produced this item. - - `"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. + The caller type. Always `direct`. - - `format: optional object { type } or object { definition, syntax, type }` + - `"direct"` - The input format for the custom tool. Default is unconstrained text. + - `Program object { caller_id, type }` - - `Text object { type }` + - `caller_id: string` - Unconstrained free-form text. + The call ID of the program item that produced this tool call. - - `type: "text"` + - `type: "program"` - Unconstrained text format. Always `text`. + The caller type. Always `program`. - - `"text"` + - `"program"` - - `Grammar object { definition, syntax, type }` + - `usage: BetaResponseUsage` - A grammar defined by the user. + Token accounting for the compaction pass, including cached, reasoning, and total tokens. - - `definition: string` + - `input_tokens: number` - The grammar definition. + The number of input tokens. - - `syntax: "lark" or "regex"` + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` - The syntax of the grammar definition. One of `lark` or `regex`. + A detailed breakdown of the input tokens. - - `"lark"` + - `cache_write_tokens: number` - - `"regex"` + The number of input tokens that were written to the cache. - - `type: "grammar"` + - `cached_tokens: number` - Grammar format. Always `grammar`. + The number of tokens that were retrieved from the cache. + [More on prompt caching](/docs/guides/prompt-caching). - - `"grammar"` + - `output_tokens: number` - - `type: "namespace"` + The number of output tokens. - The type of the tool. Always `namespace`. + - `output_tokens_details: object { reasoning_tokens }` - - `"namespace"` + A detailed breakdown of the output tokens. - - `ToolSearch object { type, description, execution, parameters }` + - `reasoning_tokens: number` - Hosted or BYOT tool search configuration for deferred tools. + The number of reasoning tokens. - - `type: "tool_search"` + - `total_tokens: number` - The type of the tool. Always `tool_search`. + The total number of tokens used. - - `"tool_search"` +### Beta Computer Action - - `description: optional string` +- `BetaComputerAction = object { button, type, x, 2 more } or object { keys, type, x, y } or object { path, type, keys } or 6 more` - Description shown to the model for a client-executed tool search tool. + A click action. - - `execution: optional "server" or "client"` + - `Click object { button, type, x, 2 more }` - Whether tool search is executed by the server or by the client. + A click action. - - `"server"` + - `button: "left" or "right" or "wheel" or 2 more` - - `"client"` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `parameters: optional unknown` + - `"left"` - Parameter schema for a client-executed tool search tool. + - `"right"` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `"wheel"` - 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). + - `"back"` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `"forward"` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `type: "click"` - - `"web_search_preview"` + Specifies the event type. For a click action, this property is always `click`. - - `"web_search_preview_2025_03_11"` + - `"click"` - - `search_content_types: optional array of "text" or "image"` + - `x: number` - - `"text"` + The x-coordinate where the click occurred. - - `"image"` + - `y: number` - - `search_context_size: optional "low" or "medium" or "high"` + The y-coordinate where the click occurred. - 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. + - `keys: optional array of string` - - `"low"` + The keys being held while clicking. - - `"medium"` + - `DoubleClick object { keys, type, x, y }` - - `"high"` + A double click action. - - `user_location: optional object { type, city, country, 2 more }` + - `keys: array of string` - The user's location. + The keys being held while double-clicking. - - `type: "approximate"` + - `type: "double_click"` - The type of location approximation. Always `approximate`. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `"approximate"` + - `"double_click"` - - `city: optional string` + - `x: number` - Free text input for the city of the user, e.g. `San Francisco`. + The x-coordinate where the double click occurred. - - `country: optional string` + - `y: number` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The y-coordinate where the double click occurred. - - `region: optional string` + - `Drag object { path, type, keys }` - Free text input for the region of the user, e.g. `California`. + A drag action. - - `timezone: optional string` + - `path: array of object { x, y }` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `ApplyPatch object { type, allowed_callers }` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - Allows the assistant to create, delete, or update files using unified diffs. + - `x: number` - - `type: "apply_patch"` + The x-coordinate. - The type of the tool. Always `apply_patch`. + - `y: number` - - `"apply_patch"` + The y-coordinate. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "drag"` - The tool invocation context(s). + Specifies the event type. For a drag action, this property is always set to `drag`. - - `"direct"` + - `"drag"` - - `"programmatic"` + - `keys: optional array of string` - - `top_p: number` + The keys being held while dragging the mouse. - 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. + - `Keypress object { keys, type }` - We generally recommend altering this or `temperature` but not both. + A collection of keypresses the model would like to perform. - - `background: optional boolean` + - `keys: array of string` - Whether to run the model response in the background. - [Learn more](/docs/guides/background). + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `completed_at: optional number` + - `type: "keypress"` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `conversation: optional object { id }` + - `"keypress"` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + - `Move object { type, x, y, keys }` - - `id: string` + A mouse move action. - The unique ID of the conversation that this response was associated with. + - `type: "move"` - - `max_output_tokens: optional number` + Specifies the event type. For a move action, this property is always set to `move`. - 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). + - `"move"` - - `max_tool_calls: optional number` + - `x: 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. + The x-coordinate to move to. - - `moderation: optional object { input, output }` + - `y: number` - Moderation results for the response input and output, if moderated completions were requested. + The y-coordinate to move to. - - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + - `keys: optional array of string` - Moderation for the response input. + The keys being held while moving the mouse. - - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + - `Screenshot object { type }` - A moderation result produced for the response input or output. + A screenshot action. - - `categories: map[boolean]` + - `type: "screenshot"` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `category_applied_input_types: map[array of "text" or "image"]` + - `"screenshot"` - Which modalities of input are reflected by the score for each category. + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `"text"` + A scroll action. - - `"image"` + - `scroll_x: number` - - `category_scores: map[number]` + The horizontal scroll distance. - A dictionary of moderation categories to scores. + - `scroll_y: number` - - `flagged: boolean` + The vertical scroll distance. - A boolean indicating whether the content was flagged by any category. + - `type: "scroll"` - - `model: string` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - The moderation model that produced this result. + - `"scroll"` - - `type: "moderation_result"` + - `x: number` - The object type, which was always `moderation_result` for successful moderation results. + The x-coordinate where the scroll occurred. - - `"moderation_result"` + - `y: number` - - `Error object { code, message, type }` + The y-coordinate where the scroll occurred. - An error produced while attempting moderation for the response input or output. + - `keys: optional array of string` - - `code: string` + The keys being held while scrolling. - The error code. + - `Type object { text, type }` - - `message: string` + An action to type in text. - The error message. + - `text: string` - - `type: "error"` + The text to type. - The object type, which was always `error` for moderation failures. + - `type: "type"` - - `"error"` + Specifies the event type. For a type action, this property is always set to `type`. - - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + - `"type"` - Moderation for the response output. + - `Wait object { type }` - - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + A wait action. - A moderation result produced for the response input or output. + - `type: "wait"` - - `categories: map[boolean]` + Specifies the event type. For a wait action, this property is always set to `wait`. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `"wait"` - - `category_applied_input_types: map[array of "text" or "image"]` +### Beta Computer Action List - Which modalities of input are reflected by the score for each category. +- `BetaComputerActionList = array of BetaComputerAction` - - `"text"` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `"image"` + - `Click object { button, type, x, 2 more }` - - `category_scores: map[number]` + A click action. - A dictionary of moderation categories to scores. + - `button: "left" or "right" or "wheel" or 2 more` - - `flagged: boolean` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - A boolean indicating whether the content was flagged by any category. + - `"left"` - - `model: string` + - `"right"` - The moderation model that produced this result. + - `"wheel"` - - `type: "moderation_result"` + - `"back"` - The object type, which was always `moderation_result` for successful moderation results. + - `"forward"` - - `"moderation_result"` + - `type: "click"` - - `Error object { code, message, type }` + Specifies the event type. For a click action, this property is always `click`. - An error produced while attempting moderation for the response input or output. + - `"click"` - - `code: string` + - `x: number` - The error code. + The x-coordinate where the click occurred. - - `message: string` + - `y: number` - The error message. + The y-coordinate where the click occurred. - - `type: "error"` + - `keys: optional array of string` - The object type, which was always `error` for moderation failures. + The keys being held while clicking. - - `"error"` + - `DoubleClick object { keys, type, x, y }` - - `output_text: optional string` + A double click action. - 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. + - `keys: array of string` - - `previous_response_id: optional string` + The keys being held while double-clicking. - 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`. + - `type: "double_click"` - - `prompt: optional BetaResponsePrompt` + Specifies the event type. For a double click action, this property is always set to `double_click`. - Reference to a prompt template and its variables. - [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). + - `"double_click"` - - `id: string` + - `x: number` - The unique identifier of the prompt template to use. + The x-coordinate where the double click occurred. - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + - `y: number` - 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 y-coordinate where the double click occurred. - - `string` + - `Drag object { path, type, keys }` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + A drag action. - A text input to the model. + - `path: array of object { x, y }` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - An image input to the model. Learn about [image inputs](/docs/guides/vision). + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `x: number` - A file input to the model. + The x-coordinate. - - `version: optional string` + - `y: number` - Optional version of the prompt template. + The y-coordinate. - - `prompt_cache_key: optional string` + - `type: "drag"` - 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). + Specifies the event type. For a drag action, this property is always set to `drag`. - - `prompt_cache_options: optional object { mode, ttl }` + - `"drag"` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `keys: optional array of string` - - `mode: "implicit" or "explicit"` + The keys being held while dragging the mouse. - Whether implicit prompt-cache breakpoints were enabled. + - `Keypress object { keys, type }` - - `"implicit"` + A collection of keypresses the model would like to perform. - - `"explicit"` + - `keys: array of string` - - `ttl: "30m"` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - The minimum lifetime applied to each cache breakpoint. + - `type: "keypress"` - - `"30m"` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `prompt_cache_retention: optional "in_memory" or "24h"` + - `"keypress"` - Deprecated. Use `prompt_cache_options.ttl` instead. + - `Move object { type, x, y, keys }` - 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. + A mouse move action. - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `type: "move"` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + Specifies the event type. For a move action, this property is always set to `move`. - - `"in_memory"` + - `"move"` - - `"24h"` + - `x: number` - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + The x-coordinate to move to. - **gpt-5 and o-series models only** + - `y: number` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + The y-coordinate to move to. - - `context: optional "auto" or "current_turn" or "all_turns"` + - `keys: 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`. + The keys being held while moving the mouse. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `Screenshot object { type }` - - `"auto"` + A screenshot action. - - `"current_turn"` + - `type: "screenshot"` - - `"all_turns"` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `effort: optional "none" or "minimal" or "low" or 4 more` + - `"screenshot"` - 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. + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `"none"` + A scroll action. - - `"minimal"` + - `scroll_x: number` - - `"low"` + The horizontal scroll distance. - - `"medium"` + - `scroll_y: number` - - `"high"` + The vertical scroll distance. - - `"xhigh"` + - `type: "scroll"` - - `"max"` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `generate_summary: optional "auto" or "concise" or "detailed"` + - `"scroll"` - **Deprecated:** use `summary` instead. + - `x: number` - 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 x-coordinate where the scroll occurred. - - `"auto"` + - `y: number` - - `"concise"` + The y-coordinate where the scroll occurred. - - `"detailed"` + - `keys: optional array of string` - - `mode: optional string or "standard" or "pro"` + The keys being held while scrolling. - Controls the reasoning execution mode for the request. + - `Type object { text, type }` - When returned on a response, this is the effective execution mode. + An action to type in text. - - `string` + - `text: string` - - `"standard" or "pro"` + The text to type. - Controls the reasoning execution mode for the request. + - `type: "type"` - When returned on a response, this is the effective execution mode. + Specifies the event type. For a type action, this property is always set to `type`. - - `"standard"` + - `"type"` - - `"pro"` + - `Wait object { type }` - - `summary: optional "auto" or "concise" or "detailed"` + A wait action. - 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: "wait"` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + Specifies the event type. For a wait action, this property is always set to `wait`. - - `"auto"` + - `"wait"` - - `"concise"` +### Beta Container Auto - - `"detailed"` +- `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `safety_identifier: optional string` + - `type: "container_auto"` - 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). + Automatically creates a container for this request - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + - `"container_auto"` - Specifies the processing type used for serving the request. + - `file_ids: optional array of string` - - 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'. + An optional list of uploaded files to make available to your code. - 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. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `"auto"` + The memory limit for the container. - - `"default"` + - `"1g"` - - `"flex"` + - `"4g"` - - `"scale"` + - `"16g"` - - `"priority"` + - `"64g"` - - `status: optional BetaResponseStatus` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + Network access policy for the container. - - `"completed"` + - `BetaContainerNetworkPolicyDisabled object { type }` - - `"failed"` + - `type: "disabled"` - - `"in_progress"` + Disable outbound network access. Always `disabled`. - - `"cancelled"` + - `"disabled"` - - `"queued"` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `"incomplete"` + - `allowed_domains: array of string` - - `text: optional BetaResponseTextConfig` + A list of allowed domains when type is `allowlist`. - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `type: "allowlist"` - - [Text inputs and outputs](/docs/guides/text) - - [Structured Outputs](/docs/guides/structured-outputs) + Allow outbound network access only to specified domains. Always `allowlist`. - - `format: optional BetaResponseFormatTextConfig` + - `"allowlist"` - An object specifying the format that the model must output. + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - 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). + Optional domain-scoped secrets for allowlisted domains. - The default format is `{ "type": "text" }` with no additional options. + - `domain: string` - **Not recommended for gpt-4o and newer models:** + The domain associated with the secret. - 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. + - `name: string` - - `Text object { type }` + The name of the secret to inject for the domain. - Default response format. Used to generate text responses. + - `value: string` - - `type: "text"` + The secret value to inject for the domain. - The type of response format being defined. Always `text`. + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - - `"text"` + An optional list of skills referenced by id or inline data. - - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` + - `BetaSkillReference object { skill_id, type, version }` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + - `skill_id: string` - - `name: string` + The ID of the referenced skill. - 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: "skill_reference"` - - `schema: map[unknown]` + References a skill created with the /v1/skills endpoint. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `"skill_reference"` - - `type: "json_schema"` + - `version: optional string` - The type of response format being defined. Always `json_schema`. + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `"json_schema"` + - `BetaInlineSkill object { description, name, source, type }` - - `description: optional string` + - `description: string` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The description of the skill. - - `strict: optional boolean` + - `name: 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 name of the skill. - - `JSONObject object { type }` + - `source: BetaInlineSkillSource` - 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. + Inline skill payload - - `type: "json_object"` + - `data: string` - The type of response format being defined. Always `json_object`. + Base64-encoded skill zip bundle. - - `"json_object"` + - `media_type: "application/zip"` - - `verbosity: optional "low" or "medium" or "high"` + The media type of the inline skill payload. Must be `application/zip`. - 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`. + - `"application/zip"` - - `"low"` + - `type: "base64"` - - `"medium"` + The type of the inline skill source. Must be `base64`. - - `"high"` + - `"base64"` - - `top_logprobs: optional number` + - `type: "inline"` - 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. + Defines an inline skill for this request. - - `truncation: optional "auto" or "disabled"` + - `"inline"` - The truncation strategy to use for the model response. +### Beta Container Network Policy Allowlist - - `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. +- `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `"auto"` + - `allowed_domains: array of string` - - `"disabled"` + A list of allowed domains when type is `allowlist`. - - `usage: optional BetaResponseUsage` + - `type: "allowlist"` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + Allow outbound network access only to specified domains. Always `allowlist`. - - `input_tokens: number` + - `"allowlist"` - The number of input tokens. + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + Optional domain-scoped secrets for allowlisted domains. - A detailed breakdown of the input tokens. + - `domain: string` - - `cache_write_tokens: number` + The domain associated with the secret. - The number of input tokens that were written to the cache. + - `name: string` - - `cached_tokens: number` + The name of the secret to inject for the domain. - The number of tokens that were retrieved from the cache. - [More on prompt caching](/docs/guides/prompt-caching). + - `value: string` - - `output_tokens: number` + The secret value to inject for the domain. - The number of output tokens. +### Beta Container Network Policy Disabled - - `output_tokens_details: object { reasoning_tokens }` +- `BetaContainerNetworkPolicyDisabled object { type }` - A detailed breakdown of the output tokens. + - `type: "disabled"` - - `reasoning_tokens: number` + Disable outbound network access. Always `disabled`. - The number of reasoning tokens. + - `"disabled"` - - `total_tokens: number` +### Beta Container Network Policy Domain Secret - The total number of tokens used. +- `BetaContainerNetworkPolicyDomainSecret object { domain, name, value }` - - `user: optional string` + - `domain: 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 domain associated with the secret. -### Beta Response Audio Delta Event + - `name: string` -- `BetaResponseAudioDeltaEvent object { delta, sequence_number, type, agent }` + The name of the secret to inject for the domain. - Emitted when there is a partial audio response. + - `value: string` - - `delta: string` + The secret value to inject for the domain. - A chunk of Base64 encoded response audio bytes. +### Beta Container Reference - - `sequence_number: number` +- `BetaContainerReference object { container_id, type }` - A sequence number for this chunk of the stream response. + - `container_id: string` - - `type: "response.audio.delta"` + The ID of the referenced container. - The type of the event. Always `response.audio.delta`. + - `type: "container_reference"` - - `"response.audio.delta"` + References a container created with the /v1/containers endpoint - - `agent: optional object { agent_name }` + - `"container_reference"` - The agent that owns this multi-agent streaming event. +### Beta Easy Input Message - - `agent_name: string` +- `BetaEasyInputMessage object { content, role, phase, type }` - The canonical name of the agent that produced this 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. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. -### Beta Response Audio Done Event + - `content: string or BetaResponseInputMessageContentList` -- `BetaResponseAudioDoneEvent object { sequence_number, type, agent }` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - Emitted when the audio response is complete. + - `TextInput = string` - - `sequence_number: number` + A text input to the model. - The sequence number of the delta. + - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` - - `type: "response.audio.done"` + A list of one or many input items to the model, containing different content + types. - The type of the event. Always `response.audio.done`. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `"response.audio.done"` + A text input to the model. - - `agent: optional object { agent_name }` + - `text: string` - The agent that owns this multi-agent streaming event. + The text input to the model. - - `agent_name: string` + - `type: "input_text"` - The canonical name of the agent that produced this item. + The type of the input item. Always `input_text`. -### Beta Response Audio Transcript Delta Event + - `"input_text"` -- `BetaResponseAudioTranscriptDeltaEvent object { delta, sequence_number, type, agent }` + - `prompt_cache_breakpoint: optional object { mode }` - Emitted when there is a partial transcript of audio. + 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. - - `delta: string` + - `mode: "explicit"` - The partial transcript of the audio response. + The breakpoint mode. Always `explicit`. - - `sequence_number: number` + - `"explicit"` - The sequence number of this event. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `type: "response.audio.transcript.delta"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - The type of the event. Always `response.audio.transcript.delta`. + - `detail: "low" or "high" or "auto" or "original"` - - `"response.audio.transcript.delta"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `agent: optional object { agent_name }` + - `"low"` - The agent that owns this multi-agent streaming event. + - `"high"` - - `agent_name: string` + - `"auto"` - The canonical name of the agent that produced this item. + - `"original"` -### Beta Response Audio Transcript Done Event + - `type: "input_image"` -- `BetaResponseAudioTranscriptDoneEvent object { sequence_number, type, agent }` + The type of the input item. Always `input_image`. - Emitted when the full audio transcript is completed. + - `"input_image"` - - `sequence_number: number` + - `file_id: optional string` - The sequence number of this event. + The ID of the file to be sent to the model. - - `type: "response.audio.transcript.done"` + - `image_url: optional string` - The type of the event. Always `response.audio.transcript.done`. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `"response.audio.transcript.done"` + - `prompt_cache_breakpoint: optional object { mode }` - - `agent: optional object { agent_name }` + 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 agent that owns this multi-agent streaming event. + - `mode: "explicit"` - - `agent_name: string` + The breakpoint mode. Always `explicit`. - The canonical name of the agent that produced this item. + - `"explicit"` -### Beta Response Code Interpreter Call Code Delta Event + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` -- `BetaResponseCodeInterpreterCallCodeDeltaEvent object { delta, item_id, output_index, 3 more }` + A file input to the model. - Emitted when a partial code snippet is streamed by the code interpreter. + - `type: "input_file"` - - `delta: string` + The type of the input item. Always `input_file`. - The partial code snippet being streamed by the code interpreter. + - `"input_file"` - - `item_id: string` + - `detail: optional "auto" or "low" or "high"` - The unique identifier of the code interpreter tool call item. + 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`. - - `output_index: number` + - `"auto"` - The index of the output item in the response for which the code is being streamed. + - `"low"` - - `sequence_number: number` + - `"high"` - The sequence number of this event, used to order streaming events. + - `file_data: optional string` - - `type: "response.code_interpreter_call_code.delta"` + The content of the file to be sent to the model. - The type of the event. Always `response.code_interpreter_call_code.delta`. + - `file_id: optional string` - - `"response.code_interpreter_call_code.delta"` + The ID of the file to be sent to the model. - - `agent: optional object { agent_name }` + - `file_url: optional string` - The agent that owns this multi-agent streaming event. + The URL of the file to be sent to the model. - - `agent_name: string` + - `filename: optional string` - The canonical name of the agent that produced this item. + The name of the file to be sent to the model. -### Beta Response Code Interpreter Call Code Done Event + - `prompt_cache_breakpoint: optional object { mode }` -- `BetaResponseCodeInterpreterCallCodeDoneEvent object { code, item_id, output_index, 3 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. - Emitted when the code snippet is finalized by the code interpreter. + - `mode: "explicit"` - - `code: string` + The breakpoint mode. Always `explicit`. - The final code snippet output by the code interpreter. + - `"explicit"` - - `item_id: string` + - `role: "user" or "assistant" or "system" or "developer"` - The unique identifier of the code interpreter tool call item. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `output_index: number` + - `"user"` - The index of the output item in the response for which the code is finalized. + - `"assistant"` - - `sequence_number: number` + - `"system"` - The sequence number of this event, used to order streaming events. + - `"developer"` - - `type: "response.code_interpreter_call_code.done"` + - `phase: optional "commentary" or "final_answer"` - The type of the event. Always `response.code_interpreter_call_code.done`. + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `"response.code_interpreter_call_code.done"` + - `"commentary"` - - `agent: optional object { agent_name }` + - `"final_answer"` - The agent that owns this multi-agent streaming event. + - `type: optional "message"` - - `agent_name: string` + The type of the message input. Always `message`. - The canonical name of the agent that produced this item. + - `"message"` -### Beta Response Code Interpreter Call Completed Event +### Beta Inline Skill -- `BetaResponseCodeInterpreterCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` +- `BetaInlineSkill object { description, name, source, type }` - Emitted when the code interpreter call is completed. + - `description: string` - - `item_id: string` + The description of the skill. - The unique identifier of the code interpreter tool call item. + - `name: string` - - `output_index: number` + The name of the skill. - The index of the output item in the response for which the code interpreter call is completed. + - `source: BetaInlineSkillSource` - - `sequence_number: number` + Inline skill payload - The sequence number of this event, used to order streaming events. + - `data: string` - - `type: "response.code_interpreter_call.completed"` + Base64-encoded skill zip bundle. - The type of the event. Always `response.code_interpreter_call.completed`. + - `media_type: "application/zip"` - - `"response.code_interpreter_call.completed"` + The media type of the inline skill payload. Must be `application/zip`. - - `agent: optional object { agent_name }` + - `"application/zip"` - The agent that owns this multi-agent streaming event. + - `type: "base64"` - - `agent_name: string` + The type of the inline skill source. Must be `base64`. - The canonical name of the agent that produced this item. + - `"base64"` -### Beta Response Code Interpreter Call In Progress Event + - `type: "inline"` -- `BetaResponseCodeInterpreterCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + Defines an inline skill for this request. - Emitted when a code interpreter call is in progress. + - `"inline"` - - `item_id: string` +### Beta Inline Skill Source - The unique identifier of the code interpreter tool call item. +- `BetaInlineSkillSource object { data, media_type, type }` - - `output_index: number` + Inline skill payload - The index of the output item in the response for which the code interpreter call is in progress. + - `data: string` - - `sequence_number: number` + Base64-encoded skill zip bundle. - The sequence number of this event, used to order streaming events. + - `media_type: "application/zip"` - - `type: "response.code_interpreter_call.in_progress"` + The media type of the inline skill payload. Must be `application/zip`. - The type of the event. Always `response.code_interpreter_call.in_progress`. + - `"application/zip"` - - `"response.code_interpreter_call.in_progress"` + - `type: "base64"` - - `agent: optional object { agent_name }` + The type of the inline skill source. Must be `base64`. - The agent that owns this multi-agent streaming event. + - `"base64"` - - `agent_name: string` +### Beta Local Environment - The canonical name of the agent that produced this item. +- `BetaLocalEnvironment object { type, skills }` -### Beta Response Code Interpreter Call Interpreting Event + - `type: "local"` -- `BetaResponseCodeInterpreterCallInterpretingEvent object { item_id, output_index, sequence_number, 2 more }` + Use a local computer environment. - Emitted when the code interpreter is actively interpreting the code snippet. + - `"local"` - - `item_id: string` + - `skills: optional array of BetaLocalSkill` - The unique identifier of the code interpreter tool call item. + An optional list of skills. - - `output_index: number` + - `description: string` - The index of the output item in the response for which the code interpreter is interpreting code. + The description of the skill. - - `sequence_number: number` + - `name: string` - The sequence number of this event, used to order streaming events. + The name of the skill. - - `type: "response.code_interpreter_call.interpreting"` + - `path: string` - The type of the event. Always `response.code_interpreter_call.interpreting`. + The path to the directory containing the skill. - - `"response.code_interpreter_call.interpreting"` +### Beta Local Skill - - `agent: optional object { agent_name }` +- `BetaLocalSkill object { description, name, path }` - The agent that owns this multi-agent streaming event. + - `description: string` - - `agent_name: string` + The description of the skill. - The canonical name of the agent that produced this item. + - `name: string` -### Beta Response Completed Event + The name of the skill. -- `BetaResponseCompletedEvent object { response, sequence_number, type, agent }` + - `path: string` - Emitted when the model response is complete. + The path to the directory containing the skill. - - `response: BetaResponse` +### Beta Response - Properties of the completed response. +- `BetaResponse object { id, created_at, error, 32 more }` - `id: string` @@ -77842,522 +75126,137 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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). - - `sequence_number: number` - - The sequence number for this event. - - - `type: "response.completed"` - - The type of the event. Always `response.completed`. - - - `"response.completed"` - - - `agent: optional object { agent_name }` - - The agent that owns this multi-agent streaming event. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - -### Beta Response Computer Tool Call Output Screenshot - -- `BetaResponseComputerToolCallOutputScreenshot object { type, file_id, image_url }` - - A computer screenshot image used with the computer use tool. - - - `type: "computer_screenshot"` - - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. - - - `"computer_screenshot"` - - - `file_id: optional string` - - The identifier of an uploaded file that contains the screenshot. - - - `image_url: optional string` - - The URL of the screenshot image. - -### Beta Response Container Reference - -- `BetaResponseContainerReference 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"` - -### Beta Response Content - -- `BetaResponseContent = BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile or 3 more` - - Multi-modal input and output contents. - - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `text: string` - - The text input to the model. - - - `type: "input_text"` - - The type of the input item. Always `input_text`. - - - `"input_text"` - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `"explicit"` - - - `BetaResponseInputImage 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"` - - - `"high"` - - - `"auto"` - - - `"original"` - - - `type: "input_image"` - - The type of the input item. Always `input_image`. - - - `"input_image"` - - - `file_id: optional string` - - The ID of the file to be sent to the model. - - - `image_url: optional string` - - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `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"` - - - `BetaResponseInputFile 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"` - - - `BetaResponseOutputText 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. +### Beta Response Audio Delta Event - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` +- `BetaResponseAudioDeltaEvent object { delta, sequence_number, type, agent }` - A citation for a container file used to generate a model response. + Emitted when there is a partial audio response. - - `container_id: string` + - `delta: string` - The ID of the container file. + A chunk of Base64 encoded response audio bytes. - - `end_index: number` + - `sequence_number: number` - The index of the last character of the container file citation in the message. + A sequence number for this chunk of the stream response. - - `file_id: string` + - `type: "response.audio.delta"` - The ID of the file. + The type of the event. Always `response.audio.delta`. - - `filename: string` + - `"response.audio.delta"` - The filename of the container file cited. + - `agent: optional object { agent_name }` - - `start_index: number` + The agent that owns this multi-agent streaming event. - The index of the first character of the container file citation in the message. + - `agent_name: string` - - `type: "container_file_citation"` + The canonical name of the agent that produced this item. - The type of the container file citation. Always `container_file_citation`. +### Beta Response Audio Done Event - - `"container_file_citation"` +- `BetaResponseAudioDoneEvent object { sequence_number, type, agent }` - - `FilePath object { file_id, index, type }` + Emitted when the audio response is complete. - A path to a file. + - `sequence_number: number` - - `file_id: string` + The sequence number of the delta. - The ID of the file. + - `type: "response.audio.done"` - - `index: number` + The type of the event. Always `response.audio.done`. - The index of the file in the list of files. + - `"response.audio.done"` - - `type: "file_path"` + - `agent: optional object { agent_name }` - The type of the file path. Always `file_path`. + The agent that owns this multi-agent streaming event. - - `"file_path"` + - `agent_name: string` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + The canonical name of the agent that produced this item. - - `token: string` +### Beta Response Audio Transcript Delta Event - - `bytes: array of number` +- `BetaResponseAudioTranscriptDeltaEvent object { delta, sequence_number, type, agent }` - - `logprob: number` + Emitted when there is a partial transcript of audio. - - `top_logprobs: array of object { token, bytes, logprob }` + - `delta: string` - - `token: string` + The partial transcript of the audio response. - - `bytes: array of number` + - `sequence_number: number` - - `logprob: number` + The sequence number of this event. - - `text: string` + - `type: "response.audio.transcript.delta"` - The text output from the model. + The type of the event. Always `response.audio.transcript.delta`. - - `type: "output_text"` + - `"response.audio.transcript.delta"` - The type of the output text. Always `output_text`. + - `agent: optional object { agent_name }` - - `"output_text"` + The agent that owns this multi-agent streaming event. - - `BetaResponseOutputRefusal object { refusal, type }` + - `agent_name: string` - A refusal from the model. + The canonical name of the agent that produced this item. - - `refusal: string` +### Beta Response Audio Transcript Done Event - The refusal explanation from the model. +- `BetaResponseAudioTranscriptDoneEvent object { sequence_number, type, agent }` - - `type: "refusal"` + Emitted when the full audio transcript is completed. - The type of the refusal. Always `refusal`. + - `sequence_number: number` - - `"refusal"` + The sequence number of this event. - - `ReasoningText object { text, type }` + - `type: "response.audio.transcript.done"` - Reasoning text from the model. + The type of the event. Always `response.audio.transcript.done`. - - `text: string` + - `"response.audio.transcript.done"` - The reasoning text from the model. + - `agent: optional object { agent_name }` - - `type: "reasoning_text"` + The agent that owns this multi-agent streaming event. - The type of the reasoning text. Always `reasoning_text`. + - `agent_name: string` - - `"reasoning_text"` + The canonical name of the agent that produced this item. -### Beta Response Content Part Added Event +### Beta Response Code Interpreter Call Code Delta Event -- `BetaResponseContentPartAddedEvent object { content_index, item_id, output_index, 4 more }` +- `BetaResponseCodeInterpreterCallCodeDeltaEvent object { delta, item_id, output_index, 3 more }` - Emitted when a new content part is added. + Emitted when a partial code snippet is streamed by the code interpreter. - - `content_index: number` + - `delta: string` - The index of the content part that was added. + The partial code snippet being streamed by the code interpreter. - `item_id: string` - The ID of the output item that the content part was added to. + The unique identifier of the code interpreter tool call item. - `output_index: number` - The index of the output item that the content part was added to. - - - `part: BetaResponseOutputText or BetaResponseOutputRefusal or object { text, type }` - - The content part that was added. - - - `BetaResponseOutputText 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"` - - - `BetaResponseOutputRefusal 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"` - - - `ReasoningText object { text, type }` - - Reasoning text from the model. - - - `text: string` - - The reasoning text from the model. - - - `type: "reasoning_text"` - - The type of the reasoning text. Always `reasoning_text`. - - - `"reasoning_text"` + The index of the output item in the response for which the code is being streamed. - `sequence_number: number` - The sequence number of this event. + The sequence number of this event, used to order streaming events. - - `type: "response.content_part.added"` + - `type: "response.code_interpreter_call_code.delta"` - The type of the event. Always `response.content_part.added`. + The type of the event. Always `response.code_interpreter_call_code.delta`. - - `"response.content_part.added"` + - `"response.code_interpreter_call_code.delta"` - `agent: optional object { agent_name }` @@ -78367,195 +75266,129 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. -### Beta Response Content Part Done Event +### Beta Response Code Interpreter Call Code Done Event -- `BetaResponseContentPartDoneEvent object { content_index, item_id, output_index, 4 more }` +- `BetaResponseCodeInterpreterCallCodeDoneEvent object { code, item_id, output_index, 3 more }` - Emitted when a content part is done. + Emitted when the code snippet is finalized by the code interpreter. - - `content_index: number` + - `code: string` - The index of the content part that is done. + The final code snippet output by the code interpreter. - `item_id: string` - The ID of the output item that the content part was added to. + The unique identifier of the code interpreter tool call item. - `output_index: number` - The index of the output item that the content part was added to. - - - `part: BetaResponseOutputText or BetaResponseOutputRefusal or object { text, type }` - - The content part that is done. - - - `BetaResponseOutputText 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 index of the output item in the response for which the code is finalized. - The ID of the container file. + - `sequence_number: number` - - `end_index: number` + The sequence number of this event, used to order streaming events. - The index of the last character of the container file citation in the message. + - `type: "response.code_interpreter_call_code.done"` - - `file_id: string` + The type of the event. Always `response.code_interpreter_call_code.done`. - The ID of the file. + - `"response.code_interpreter_call_code.done"` - - `filename: string` + - `agent: optional object { agent_name }` - The filename of the container file cited. + The agent that owns this multi-agent streaming event. - - `start_index: number` + - `agent_name: string` - The index of the first character of the container file citation in the message. + The canonical name of the agent that produced this item. - - `type: "container_file_citation"` +### Beta Response Code Interpreter Call Completed Event - The type of the container file citation. Always `container_file_citation`. +- `BetaResponseCodeInterpreterCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - - `"container_file_citation"` + Emitted when the code interpreter call is completed. - - `FilePath object { file_id, index, type }` + - `item_id: string` - A path to a file. + The unique identifier of the code interpreter tool call item. - - `file_id: string` + - `output_index: number` - The ID of the file. + The index of the output item in the response for which the code interpreter call is completed. - - `index: number` + - `sequence_number: number` - The index of the file in the list of files. + The sequence number of this event, used to order streaming events. - - `type: "file_path"` + - `type: "response.code_interpreter_call.completed"` - The type of the file path. Always `file_path`. + The type of the event. Always `response.code_interpreter_call.completed`. - - `"file_path"` + - `"response.code_interpreter_call.completed"` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `agent: optional object { agent_name }` - - `token: string` + The agent that owns this multi-agent streaming event. - - `bytes: array of number` + - `agent_name: string` - - `logprob: number` + The canonical name of the agent that produced this item. - - `top_logprobs: array of object { token, bytes, logprob }` +### Beta Response Code Interpreter Call In Progress Event - - `token: string` +- `BetaResponseCodeInterpreterCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` - - `bytes: array of number` + Emitted when a code interpreter call is in progress. - - `logprob: number` + - `item_id: string` - - `text: string` + The unique identifier of the code interpreter tool call item. - The text output from the model. + - `output_index: number` - - `type: "output_text"` + The index of the output item in the response for which the code interpreter call is in progress. - The type of the output text. Always `output_text`. + - `sequence_number: number` - - `"output_text"` + The sequence number of this event, used to order streaming events. - - `BetaResponseOutputRefusal object { refusal, type }` + - `type: "response.code_interpreter_call.in_progress"` - A refusal from the model. + The type of the event. Always `response.code_interpreter_call.in_progress`. - - `refusal: string` + - `"response.code_interpreter_call.in_progress"` - The refusal explanation from the model. + - `agent: optional object { agent_name }` - - `type: "refusal"` + The agent that owns this multi-agent streaming event. - The type of the refusal. Always `refusal`. + - `agent_name: string` - - `"refusal"` + The canonical name of the agent that produced this item. - - `ReasoningText object { text, type }` +### Beta Response Code Interpreter Call Interpreting Event - Reasoning text from the model. +- `BetaResponseCodeInterpreterCallInterpretingEvent object { item_id, output_index, sequence_number, 2 more }` - - `text: string` + Emitted when the code interpreter is actively interpreting the code snippet. - The reasoning text from the model. + - `item_id: string` - - `type: "reasoning_text"` + The unique identifier of the code interpreter tool call item. - The type of the reasoning text. Always `reasoning_text`. + - `output_index: number` - - `"reasoning_text"` + The index of the output item in the response for which the code interpreter is interpreting code. - `sequence_number: number` - The sequence number of this event. + The sequence number of this event, used to order streaming events. - - `type: "response.content_part.done"` + - `type: "response.code_interpreter_call.interpreting"` - The type of the event. Always `response.content_part.done`. + The type of the event. Always `response.code_interpreter_call.interpreting`. - - `"response.content_part.done"` + - `"response.code_interpreter_call.interpreting"` - `agent: optional object { agent_name }` @@ -78565,25 +75398,15 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. -### Beta Response Conversation Param - -- `BetaResponseConversationParam object { id }` - - The conversation that this response belongs to. - - - `id: string` - - The unique ID of the conversation. - -### Beta Response Created Event +### Beta Response Completed Event -- `BetaResponseCreatedEvent object { response, sequence_number, type, agent }` +- `BetaResponseCompletedEvent object { response, sequence_number, type, agent }` - An event that is emitted when a response is created. + Emitted when the model response is complete. - `response: BetaResponse` - The response that was created. + Properties of the completed response. - `id: string` @@ -89330,11 +86153,11 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The sequence number for this event. - - `type: "response.created"` + - `type: "response.completed"` - The type of the event. Always `response.created`. + The type of the event. Always `response.completed`. - - `"response.created"` + - `"response.completed"` - `agent: optional object { agent_name }` @@ -89344,33 +86167,504 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. -### Beta Response Custom Tool Call Input Delta Event +### Beta Response Computer Tool Call Output Screenshot -- `BetaResponseCustomToolCallInputDeltaEvent object { delta, item_id, output_index, 3 more }` +- `BetaResponseComputerToolCallOutputScreenshot object { type, file_id, image_url }` - Event representing a delta (partial update) to the input of a custom tool call. + A computer screenshot image used with the computer use tool. - - `delta: string` + - `type: "computer_screenshot"` - The incremental input data (delta) for the custom tool call. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. + + - `"computer_screenshot"` + + - `file_id: optional string` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: optional string` + + The URL of the screenshot image. + +### Beta Response Container Reference + +- `BetaResponseContainerReference 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"` + +### Beta Response Content + +- `BetaResponseContent = BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile or 3 more` + + Multi-modal input and output contents. + + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `"input_text"` + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `BetaResponseInputImage 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"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `"input_image"` + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `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"` + + - `BetaResponseInputFile 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"` + + - `BetaResponseOutputText 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"` + + - `BetaResponseOutputRefusal 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"` + + - `ReasoningText object { text, type }` + + Reasoning text from the model. + + - `text: string` + + The reasoning text from the model. + + - `type: "reasoning_text"` + + The type of the reasoning text. Always `reasoning_text`. + + - `"reasoning_text"` + +### Beta Response Content Part Added Event + +- `BetaResponseContentPartAddedEvent object { content_index, item_id, output_index, 4 more }` + + Emitted when a new content part is added. + + - `content_index: number` + + The index of the content part that was added. - `item_id: string` - Unique identifier for the API item associated with this event. + The ID of the output item that the content part was added to. - `output_index: number` - The index of the output this delta applies to. + The index of the output item that the content part was added to. + + - `part: BetaResponseOutputText or BetaResponseOutputRefusal or object { text, type }` + + The content part that was added. + + - `BetaResponseOutputText 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"` + + - `BetaResponseOutputRefusal 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"` + + - `ReasoningText object { text, type }` + + Reasoning text from the model. + + - `text: string` + + The reasoning text from the model. + + - `type: "reasoning_text"` + + The type of the reasoning text. Always `reasoning_text`. + + - `"reasoning_text"` - `sequence_number: number` The sequence number of this event. - - `type: "response.custom_tool_call_input.delta"` + - `type: "response.content_part.added"` - The event type identifier. + The type of the event. Always `response.content_part.added`. - - `"response.custom_tool_call_input.delta"` + - `"response.content_part.added"` - `agent: optional object { agent_name }` @@ -89380,123 +86674,195 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. -### Beta Response Custom Tool Call Input Done Event +### Beta Response Content Part Done Event -- `BetaResponseCustomToolCallInputDoneEvent object { input, item_id, output_index, 3 more }` +- `BetaResponseContentPartDoneEvent object { content_index, item_id, output_index, 4 more }` - Event indicating that input for a custom tool call is complete. + Emitted when a content part is done. - - `input: string` + - `content_index: number` - The complete input data for the custom tool call. + The index of the content part that is done. - `item_id: string` - Unique identifier for the API item associated with this event. + The ID of the output item that the content part was added to. - `output_index: number` - The index of the output this event applies to. + The index of the output item that the content part was added to. - - `sequence_number: number` + - `part: BetaResponseOutputText or BetaResponseOutputRefusal or object { text, type }` - The sequence number of this event. + The content part that is done. - - `type: "response.custom_tool_call_input.done"` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - The event type identifier. + A text output from the model. - - `"response.custom_tool_call_input.done"` + - `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 }` - - `agent: optional object { agent_name }` + The annotations of the text output. - The agent that owns this multi-agent streaming event. + - `FileCitation object { file_id, filename, index, type }` - - `agent_name: string` + A citation to a file. - The canonical name of the agent that produced this item. + - `file_id: string` -### Beta Response Error + The ID of the file. -- `BetaResponseError object { code, message }` + - `filename: string` - An error object returned when the model fails to generate a Response. + The filename of the file cited. - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 17 more` + - `index: number` - The error code for the response. + The index of the file in the list of files. - - `"server_error"` + - `type: "file_citation"` - - `"rate_limit_exceeded"` + The type of the file citation. Always `file_citation`. - - `"invalid_prompt"` + - `"file_citation"` - - `"data_residency_mismatch"` + - `URLCitation object { end_index, start_index, title, 2 more }` - - `"bio_policy"` + A citation for a web resource used to generate a model response. - - `"vector_store_timeout"` + - `end_index: number` - - `"invalid_image"` + The index of the last character of the URL citation in the message. - - `"invalid_image_format"` + - `start_index: number` - - `"invalid_base64_image"` + The index of the first character of the URL citation in the message. - - `"invalid_image_url"` + - `title: string` - - `"image_too_large"` + The title of the web resource. - - `"image_too_small"` + - `type: "url_citation"` - - `"image_parse_error"` + The type of the URL citation. Always `url_citation`. - - `"image_content_policy_violation"` + - `"url_citation"` - - `"invalid_image_mode"` + - `url: string` - - `"image_file_too_large"` + The URL of the web resource. - - `"unsupported_image_media_type"` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - - `"empty_image_file"` + A citation for a container file used to generate a model response. - - `"failed_to_download_image"` + - `container_id: string` - - `"image_file_not_found"` + The ID of the container file. - - `message: string` + - `end_index: number` - A human-readable description of the error. + The index of the last character of the container file citation in the message. -### Beta Response Error Event + - `file_id: string` -- `BetaResponseErrorEvent object { code, message, param, 3 more }` + The ID of the file. - Emitted when an error occurs. + - `filename: string` - - `code: string` + The filename of the container file cited. - The error code. + - `start_index: number` - - `message: string` + The index of the first character of the container file citation in the message. - The error message. + - `type: "container_file_citation"` - - `param: string` + The type of the container file citation. Always `container_file_citation`. - The error parameter. + - `"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"` + + - `BetaResponseOutputRefusal 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"` + + - `ReasoningText object { text, type }` + + Reasoning text from the model. + + - `text: string` + + The reasoning text from the model. + + - `type: "reasoning_text"` + + The type of the reasoning text. Always `reasoning_text`. + + - `"reasoning_text"` - `sequence_number: number` The sequence number of this event. - - `type: "error"` + - `type: "response.content_part.done"` - The type of the event. Always `error`. + The type of the event. Always `response.content_part.done`. - - `"error"` + - `"response.content_part.done"` - `agent: optional object { agent_name }` @@ -89506,15 +86872,25 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. -### Beta Response Failed Event +### Beta Response Conversation Param -- `BetaResponseFailedEvent object { response, sequence_number, type, agent }` +- `BetaResponseConversationParam object { id }` - An event that is emitted when a response fails. + The conversation that this response belongs to. + + - `id: string` + + The unique ID of the conversation. + +### Beta Response Created Event + +- `BetaResponseCreatedEvent object { response, sequence_number, type, agent }` + + An event that is emitted when a response is created. - `response: BetaResponse` - The response that failed. + The response that was created. - `id: string` @@ -100259,109 +97635,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `sequence_number: number` - The sequence number of this event. - - - `type: "response.failed"` - - The type of the event. Always `response.failed`. - - - `"response.failed"` - - - `agent: optional object { agent_name }` - - The agent that owns this multi-agent streaming event. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - -### Beta Response File Search Call Completed Event - -- `BetaResponseFileSearchCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - - Emitted when a file search call is completed (results found). - - - `item_id: string` - - The ID of the output item that the file search call is initiated. - - - `output_index: number` - - The index of the output item that the file search call is initiated. - - - `sequence_number: number` - - The sequence number of this event. - - - `type: "response.file_search_call.completed"` - - The type of the event. Always `response.file_search_call.completed`. - - - `"response.file_search_call.completed"` - - - `agent: optional object { agent_name }` - - The agent that owns this multi-agent streaming event. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - -### Beta Response File Search Call In Progress Event - -- `BetaResponseFileSearchCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` - - Emitted when a file search call is initiated. - - - `item_id: string` - - The ID of the output item that the file search call is initiated. - - - `output_index: number` - - The index of the output item that the file search call is initiated. - - - `sequence_number: number` - - The sequence number of this event. - - - `type: "response.file_search_call.in_progress"` - - The type of the event. Always `response.file_search_call.in_progress`. - - - `"response.file_search_call.in_progress"` - - - `agent: optional object { agent_name }` - - The agent that owns this multi-agent streaming event. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - -### Beta Response File Search Call Searching Event - -- `BetaResponseFileSearchCallSearchingEvent object { item_id, output_index, sequence_number, 2 more }` - - Emitted when a file search is currently searching. - - - `item_id: string` - - The ID of the output item that the file search call is initiated. - - - `output_index: number` - - The index of the output item that the file search call is searching. - - - `sequence_number: number` - - The sequence number of this event. + The sequence number for this event. - - `type: "response.file_search_call.searching"` + - `type: "response.created"` - The type of the event. Always `response.file_search_call.searching`. + The type of the event. Always `response.created`. - - `"response.file_search_call.searching"` + - `"response.created"` - `agent: optional object { agent_name }` @@ -100371,182 +97651,33 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. -### Beta Response Format Text Config - -- `BetaResponseFormatTextConfig = object { type } or BetaResponseFormatTextJSONSchemaConfig or object { type }` - - 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. - - - `Text object { type }` - - Default response format. Used to generate text responses. - - - `type: "text"` - - The type of response format being defined. Always `text`. - - - `"text"` - - - `BetaResponseFormatTextJSONSchemaConfig 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). - - - `JSONObject 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"` - -### Beta Response Format Text JSON Schema Config - -- `BetaResponseFormatTextJSONSchemaConfig 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). - -### Beta Response Function Call Arguments Delta Event +### Beta Response Custom Tool Call Input Delta Event -- `BetaResponseFunctionCallArgumentsDeltaEvent object { delta, item_id, output_index, 3 more }` +- `BetaResponseCustomToolCallInputDeltaEvent object { delta, item_id, output_index, 3 more }` - Emitted when there is a partial function-call arguments delta. + Event representing a delta (partial update) to the input of a custom tool call. - `delta: string` - The function-call arguments delta that is added. + The incremental input data (delta) for the custom tool call. - `item_id: string` - The ID of the output item that the function-call arguments delta is added to. + Unique identifier for the API item associated with this event. - `output_index: number` - The index of the output item that the function-call arguments delta is added to. + The index of the output this delta applies to. - `sequence_number: number` The sequence number of this event. - - `type: "response.function_call_arguments.delta"` - - The type of the event. Always `response.function_call_arguments.delta`. - - - `"response.function_call_arguments.delta"` - - - `agent: optional object { agent_name }` - - The agent that owns this multi-agent streaming event. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - -### Beta Response Function Call Arguments Done Event - -- `BetaResponseFunctionCallArgumentsDoneEvent object { arguments, item_id, name, 4 more }` - - Emitted when function-call arguments are finalized. - - - `arguments: string` - - The function-call arguments. - - - `item_id: string` - - The ID of the item. - - - `name: string` - - The name of the function that was called. - - - `output_index: number` - - The index of the output item. - - - `sequence_number: number` - - The sequence number of this event. + - `type: "response.custom_tool_call_input.delta"` - - `type: "response.function_call_arguments.done"` + The event type identifier. - - `"response.function_call_arguments.done"` + - `"response.custom_tool_call_input.delta"` - `agent: optional object { agent_name }` @@ -100556,71 +97687,33 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. -### Beta Response Function Shell Call Output Content - -- `BetaResponseFunctionShellCallOutputContent object { outcome, stderr, stdout }` - - Captured stdout and stderr for a portion of a shell tool call output. - - - `outcome: object { type } or object { exit_code, type }` - - The exit or timeout outcome associated with this shell call. - - - `Timeout object { type }` - - Indicates that the shell call exceeded its configured time limit. - - - `type: "timeout"` - - The outcome type. Always `timeout`. - - - `"timeout"` - - - `Exit object { exit_code, type }` - - Indicates that the shell commands finished and returned an exit code. - - - `exit_code: number` - - The exit code returned by the shell process. - - - `type: "exit"` - - The outcome type. Always `exit`. - - - `"exit"` - - - `stderr: string` - - Captured stderr output for the shell call. - - - `stdout: string` +### Beta Response Custom Tool Call Input Done Event - Captured stdout output for the shell call. +- `BetaResponseCustomToolCallInputDoneEvent object { input, item_id, output_index, 3 more }` -### Beta Response Image Gen Call Completed Event + Event indicating that input for a custom tool call is complete. -- `BetaResponseImageGenCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` + - `input: string` - Emitted when an image generation tool call has completed and the final image is available. + The complete input data for the custom tool call. - `item_id: string` - The unique identifier of the image generation item being processed. + Unique identifier for the API item associated with this event. - `output_index: number` - The index of the output item in the response's output array. + The index of the output this event applies to. - `sequence_number: number` The sequence number of this event. - - `type: "response.image_generation_call.completed"` + - `type: "response.custom_tool_call_input.done"` - The type of the event. Always 'response.image_generation_call.completed'. + The event type identifier. - - `"response.image_generation_call.completed"` + - `"response.custom_tool_call_input.done"` - `agent: optional object { agent_name }` @@ -100630,101 +97723,87 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. -### Beta Response Image Gen Call Generating Event - -- `BetaResponseImageGenCallGeneratingEvent object { item_id, output_index, sequence_number, 2 more }` - - Emitted when an image generation tool call is actively generating an image (intermediate state). - - - `item_id: string` - - The unique identifier of the image generation item being processed. - - - `output_index: number` - - The index of the output item in the response's output array. - - - `sequence_number: number` +### Beta Response Error - The sequence number of the image generation item being processed. +- `BetaResponseError object { code, message }` - - `type: "response.image_generation_call.generating"` + An error object returned when the model fails to generate a Response. - The type of the event. Always 'response.image_generation_call.generating'. + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 17 more` - - `"response.image_generation_call.generating"` + The error code for the response. - - `agent: optional object { agent_name }` + - `"server_error"` - The agent that owns this multi-agent streaming event. + - `"rate_limit_exceeded"` - - `agent_name: string` + - `"invalid_prompt"` - The canonical name of the agent that produced this item. + - `"data_residency_mismatch"` -### Beta Response Image Gen Call In Progress Event + - `"bio_policy"` -- `BetaResponseImageGenCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + - `"vector_store_timeout"` - Emitted when an image generation tool call is in progress. + - `"invalid_image"` - - `item_id: string` + - `"invalid_image_format"` - The unique identifier of the image generation item being processed. + - `"invalid_base64_image"` - - `output_index: number` + - `"invalid_image_url"` - The index of the output item in the response's output array. + - `"image_too_large"` - - `sequence_number: number` + - `"image_too_small"` - The sequence number of the image generation item being processed. + - `"image_parse_error"` - - `type: "response.image_generation_call.in_progress"` + - `"image_content_policy_violation"` - The type of the event. Always 'response.image_generation_call.in_progress'. + - `"invalid_image_mode"` - - `"response.image_generation_call.in_progress"` + - `"image_file_too_large"` - - `agent: optional object { agent_name }` + - `"unsupported_image_media_type"` - The agent that owns this multi-agent streaming event. + - `"empty_image_file"` - - `agent_name: string` + - `"failed_to_download_image"` - The canonical name of the agent that produced this item. + - `"image_file_not_found"` -### Beta Response Image Gen Call Partial Image Event + - `message: string` -- `BetaResponseImageGenCallPartialImageEvent object { item_id, output_index, partial_image_b64, 4 more }` + A human-readable description of the error. - Emitted when a partial image is available during image generation streaming. +### Beta Response Error Event - - `item_id: string` +- `BetaResponseErrorEvent object { code, message, param, 3 more }` - The unique identifier of the image generation item being processed. + Emitted when an error occurs. - - `output_index: number` + - `code: string` - The index of the output item in the response's output array. + The error code. - - `partial_image_b64: string` + - `message: string` - Base64-encoded partial image data, suitable for rendering as an image. + The error message. - - `partial_image_index: number` + - `param: string` - 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). + The error parameter. - `sequence_number: number` - The sequence number of the image generation item being processed. + The sequence number of this event. - - `type: "response.image_generation_call.partial_image"` + - `type: "error"` - The type of the event. Always 'response.image_generation_call.partial_image'. + The type of the event. Always `error`. - - `"response.image_generation_call.partial_image"` + - `"error"` - `agent: optional object { agent_name }` @@ -100734,15 +97813,15 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. -### Beta Response In Progress Event +### Beta Response Failed Event -- `BetaResponseInProgressEvent object { response, sequence_number, type, agent }` +- `BetaResponseFailedEvent object { response, sequence_number, type, agent }` - Emitted when the response is in progress. + An event that is emitted when a response fails. - `response: BetaResponse` - The response that is in progress. + The response that failed. - `id: string` @@ -111489,11 +108568,11 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The sequence number of this event. - - `type: "response.in_progress"` + - `type: "response.failed"` - The type of the event. Always `response.in_progress`. + The type of the event. Always `response.failed`. - - `"response.in_progress"` + - `"response.failed"` - `agent: optional object { agent_name }` @@ -111503,46 +108582,474 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. -### Beta Response Includable +### Beta Response File Search Call Completed Event -- `BetaResponseIncludable = "file_search_call.results" or "web_search_call.results" or "web_search_call.action.sources" or 5 more` +- `BetaResponseFileSearchCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - Specify additional output data to include in the model response. Currently supported values are: + Emitted when a file search call is completed (results found). - - `web_search_call.results`: Include the search results of the web search tool call. - - `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). + - `item_id: string` - - `"file_search_call.results"` + The ID of the output item that the file search call is initiated. - - `"web_search_call.results"` + - `output_index: number` - - `"web_search_call.action.sources"` + The index of the output item that the file search call is initiated. - - `"message.input_image.image_url"` + - `sequence_number: number` - - `"computer_call_output.output.image_url"` + The sequence number of this event. - - `"code_interpreter_call.outputs"` + - `type: "response.file_search_call.completed"` - - `"reasoning.encrypted_content"` + The type of the event. Always `response.file_search_call.completed`. - - `"message.output_text.logprobs"` + - `"response.file_search_call.completed"` -### Beta Response Incomplete Event + - `agent: optional object { agent_name }` -- `BetaResponseIncompleteEvent object { response, sequence_number, type, agent }` + The agent that owns this multi-agent streaming event. - An event that is emitted when a response finishes as incomplete. + - `agent_name: string` + + The canonical name of the agent that produced this item. + +### Beta Response File Search Call In Progress Event + +- `BetaResponseFileSearchCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + + Emitted when a file search call is initiated. + + - `item_id: string` + + The ID of the output item that the file search call is initiated. + + - `output_index: number` + + The index of the output item that the file search call is initiated. + + - `sequence_number: number` + + The sequence number of this event. + + - `type: "response.file_search_call.in_progress"` + + The type of the event. Always `response.file_search_call.in_progress`. + + - `"response.file_search_call.in_progress"` + + - `agent: optional object { agent_name }` + + The agent that owns this multi-agent streaming event. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + +### Beta Response File Search Call Searching Event + +- `BetaResponseFileSearchCallSearchingEvent object { item_id, output_index, sequence_number, 2 more }` + + Emitted when a file search is currently searching. + + - `item_id: string` + + The ID of the output item that the file search call is initiated. + + - `output_index: number` + + The index of the output item that the file search call is searching. + + - `sequence_number: number` + + The sequence number of this event. + + - `type: "response.file_search_call.searching"` + + The type of the event. Always `response.file_search_call.searching`. + + - `"response.file_search_call.searching"` + + - `agent: optional object { agent_name }` + + The agent that owns this multi-agent streaming event. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + +### Beta Response Format Text Config + +- `BetaResponseFormatTextConfig = object { type } or BetaResponseFormatTextJSONSchemaConfig or object { type }` + + 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. + + - `Text object { type }` + + Default response format. Used to generate text responses. + + - `type: "text"` + + The type of response format being defined. Always `text`. + + - `"text"` + + - `BetaResponseFormatTextJSONSchemaConfig 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). + + - `JSONObject 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"` + +### Beta Response Format Text JSON Schema Config + +- `BetaResponseFormatTextJSONSchemaConfig 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). + +### Beta Response Function Call Arguments Delta Event + +- `BetaResponseFunctionCallArgumentsDeltaEvent object { delta, item_id, output_index, 3 more }` + + Emitted when there is a partial function-call arguments delta. + + - `delta: string` + + The function-call arguments delta that is added. + + - `item_id: string` + + The ID of the output item that the function-call arguments delta is added to. + + - `output_index: number` + + The index of the output item that the function-call arguments delta is added to. + + - `sequence_number: number` + + The sequence number of this event. + + - `type: "response.function_call_arguments.delta"` + + The type of the event. Always `response.function_call_arguments.delta`. + + - `"response.function_call_arguments.delta"` + + - `agent: optional object { agent_name }` + + The agent that owns this multi-agent streaming event. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + +### Beta Response Function Call Arguments Done Event + +- `BetaResponseFunctionCallArgumentsDoneEvent object { arguments, item_id, name, 4 more }` + + Emitted when function-call arguments are finalized. + + - `arguments: string` + + The function-call arguments. + + - `item_id: string` + + The ID of the item. + + - `name: string` + + The name of the function that was called. + + - `output_index: number` + + The index of the output item. + + - `sequence_number: number` + + The sequence number of this event. + + - `type: "response.function_call_arguments.done"` + + - `"response.function_call_arguments.done"` + + - `agent: optional object { agent_name }` + + The agent that owns this multi-agent streaming event. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + +### Beta Response Function Shell Call Output Content + +- `BetaResponseFunctionShellCallOutputContent object { outcome, stderr, stdout }` + + Captured stdout and stderr for a portion of a shell tool call output. + + - `outcome: object { type } or object { exit_code, type }` + + The exit or timeout outcome associated with this shell call. + + - `Timeout object { type }` + + Indicates that the shell call exceeded its configured time limit. + + - `type: "timeout"` + + The outcome type. Always `timeout`. + + - `"timeout"` + + - `Exit object { exit_code, type }` + + Indicates that the shell commands finished and returned an exit code. + + - `exit_code: number` + + The exit code returned by the shell process. + + - `type: "exit"` + + The outcome type. Always `exit`. + + - `"exit"` + + - `stderr: string` + + Captured stderr output for the shell call. + + - `stdout: string` + + Captured stdout output for the shell call. + +### Beta Response Image Gen Call Completed Event + +- `BetaResponseImageGenCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` + + Emitted when an image generation tool call has completed and the final image is available. + + - `item_id: string` + + The unique identifier of the image generation item being processed. + + - `output_index: number` + + The index of the output item in the response's output array. + + - `sequence_number: number` + + The sequence number of this event. + + - `type: "response.image_generation_call.completed"` + + The type of the event. Always 'response.image_generation_call.completed'. + + - `"response.image_generation_call.completed"` + + - `agent: optional object { agent_name }` + + The agent that owns this multi-agent streaming event. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + +### Beta Response Image Gen Call Generating Event + +- `BetaResponseImageGenCallGeneratingEvent object { item_id, output_index, sequence_number, 2 more }` + + Emitted when an image generation tool call is actively generating an image (intermediate state). + + - `item_id: string` + + The unique identifier of the image generation item being processed. + + - `output_index: number` + + The index of the output item in the response's output array. + + - `sequence_number: number` + + The sequence number of the image generation item being processed. + + - `type: "response.image_generation_call.generating"` + + The type of the event. Always 'response.image_generation_call.generating'. + + - `"response.image_generation_call.generating"` + + - `agent: optional object { agent_name }` + + The agent that owns this multi-agent streaming event. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + +### Beta Response Image Gen Call In Progress Event + +- `BetaResponseImageGenCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + + Emitted when an image generation tool call is in progress. + + - `item_id: string` + + The unique identifier of the image generation item being processed. + + - `output_index: number` + + The index of the output item in the response's output array. + + - `sequence_number: number` + + The sequence number of the image generation item being processed. + + - `type: "response.image_generation_call.in_progress"` + + The type of the event. Always 'response.image_generation_call.in_progress'. + + - `"response.image_generation_call.in_progress"` + + - `agent: optional object { agent_name }` + + The agent that owns this multi-agent streaming event. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + +### Beta Response Image Gen Call Partial Image Event + +- `BetaResponseImageGenCallPartialImageEvent object { item_id, output_index, partial_image_b64, 4 more }` + + Emitted when a partial image is available during image generation streaming. + + - `item_id: string` + + The unique identifier of the image generation item being processed. + + - `output_index: number` + + The index of the output item in the response's output array. + + - `partial_image_b64: string` + + Base64-encoded partial image data, suitable for rendering as an image. + + - `partial_image_index: number` + + 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). + + - `sequence_number: number` + + The sequence number of the image generation item being processed. + + - `type: "response.image_generation_call.partial_image"` + + The type of the event. Always 'response.image_generation_call.partial_image'. + + - `"response.image_generation_call.partial_image"` + + - `agent: optional object { agent_name }` + + The agent that owns this multi-agent streaming event. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + +### Beta Response In Progress Event + +- `BetaResponseInProgressEvent object { response, sequence_number, type, agent }` + + Emitted when the response is in progress. - `response: BetaResponse` - The response that was incomplete. + The response that is in progress. - `id: string` @@ -122289,11 +119796,11 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The sequence number of this event. - - `type: "response.incomplete"` + - `type: "response.in_progress"` - The type of the event. Always `response.incomplete`. + The type of the event. Always `response.in_progress`. - - `"response.incomplete"` + - `"response.in_progress"` - `agent: optional object { agent_name }` @@ -122303,43 +119810,136 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. -### Beta Response Inject Created Event +### Beta Response Includable -- `BetaResponseInjectCreatedEvent object { response_id, sequence_number, type, stream_id }` +- `BetaResponseIncludable = "file_search_call.results" or "web_search_call.results" or "web_search_call.action.sources" or 5 more` - Emitted when all injected input items were validated and committed to the - active response. + Specify additional output data to include in the model response. Currently supported values are: - - `response_id: string` + - `web_search_call.results`: Include the search results of the web search tool call. + - `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). - The ID of the response that accepted the input. + - `"file_search_call.results"` - - `sequence_number: number` + - `"web_search_call.results"` - The sequence number for this event. + - `"web_search_call.action.sources"` - - `type: "response.inject.created"` + - `"message.input_image.image_url"` - The event discriminator. Always `response.inject.created`. + - `"computer_call_output.output.image_url"` - - `"response.inject.created"` + - `"code_interpreter_call.outputs"` - - `stream_id: optional string` + - `"reasoning.encrypted_content"` - The multiplexed WebSocket stream that emitted the event. This field is - present only when WebSocket multiplexing is enabled separately. + - `"message.output_text.logprobs"` -### Beta Response Inject Event +### Beta Response Incomplete Event -- `BetaResponseInjectEvent object { input, response_id, type }` +- `BetaResponseIncompleteEvent object { response, sequence_number, type, agent }` - Injects input items into an active response over a WebSocket connection. - The items are validated and committed atomically. Currently, the server - accepts client-owned tool outputs that resume a waiting agent. + An event that is emitted when a response finishes as incomplete. - - `input: array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + - `response: BetaResponse` - Input items to inject into the active response. + The response that was incomplete. + + - `id: string` + + Unique identifier for this Response. + + - `created_at: number` + + Unix timestamp (in seconds) of when this Response was created. + + - `error: BetaResponseError` + + An error object returned when the model fails to generate a Response. + + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 17 more` + + The error code for the response. + + - `"server_error"` + + - `"rate_limit_exceeded"` + + - `"invalid_prompt"` + + - `"data_residency_mismatch"` + + - `"bio_policy"` + + - `"vector_store_timeout"` + + - `"invalid_image"` + + - `"invalid_image_format"` + + - `"invalid_base64_image"` + + - `"invalid_image_url"` + + - `"image_too_large"` + + - `"image_too_small"` + + - `"image_parse_error"` + + - `"image_content_policy_violation"` + + - `"invalid_image_mode"` + + - `"image_file_too_large"` + + - `"unsupported_image_media_type"` + + - `"empty_image_file"` + + - `"failed_to_download_image"` + + - `"image_file_not_found"` + + - `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 BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 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 + `developer` role. + + - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + + A list of one or many input items to the model, containing + different content types. - `BetaEasyInputMessage object { content, role, phase, type }` @@ -127101,237 +124701,9 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "program_output"` - The item type. Always `program_output`. - - - `"program_output"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `response_id: string` - - The ID of the active response that should receive the input. - - - `type: "response.inject"` - - The event discriminator. Always `response.inject`. - - - `"response.inject"` - -### Beta Response Inject Failed Event - -- `BetaResponseInjectFailedEvent object { error, input, response_id, 3 more }` - - Emitted when injected input could not be committed to a response. The event - returns the uncommitted raw input so the client can retry it in another - response when appropriate. - - - `error: object { code, message }` - - Information about why the input was not committed. - - - `code: "response_already_completed" or "response_not_found"` - - A machine-readable error code. - - - `"response_already_completed"` - - - `"response_not_found"` - - - `message: string` - - A human-readable description of the error. - - - `input: array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - - The raw input items that were not committed. - - - `BetaEasyInputMessage object { content, role, phase, type }` - - A message input to the model with a role indicating instruction following - hierarchy. Instructions given with the `developer` or `system` role take - precedence over instructions given with the `user` role. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. - - - `content: string or BetaResponseInputMessageContentList` - - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. - - - `TextInput = string` - - A text input to the model. - - - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` - - A list of one or many input items to the model, containing different content - types. - - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `text: string` - - The text input to the model. - - - `type: "input_text"` - - The type of the input item. Always `input_text`. - - - `"input_text"` - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `"explicit"` - - - `BetaResponseInputImage 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"` - - - `"high"` - - - `"auto"` - - - `"original"` - - - `type: "input_image"` - - The type of the input item. Always `input_image`. - - - `"input_image"` - - - `file_id: optional string` - - The ID of the file to be sent to the model. - - - `image_url: optional string` - - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `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"` - - - `BetaResponseInputFile 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, agent, 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. - - - `content: BetaResponseInputMessageContentList` - - 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"` + The item type. Always `program_output`. - - `"developer"` + - `"program_output"` - `agent: optional object { agent_name }` @@ -127341,219 +124713,241 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `metadata: map[string]` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + 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. - - `"in_progress"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"completed"` + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - - `"incomplete"` + 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: optional "message"` + - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` - The type of the message input. Always set to `message`. + 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. - - `"message"` + - `"gpt-5.6-sol"` - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + - `"gpt-5.6-terra"` - An output message from the model. + - `"gpt-5.6-luna"` - - `id: string` + - `"gpt-5.4"` - The unique ID of the output message. + - `"gpt-5.4-mini"` - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `"gpt-5.4-nano"` - The content of the output message. + - `"gpt-5.4-mini-2026-03-17"` - - `BetaResponseOutputText object { annotations, logprobs, text, type }` + - `"gpt-5.4-nano-2026-03-17"` - A text output from the model. + - `"gpt-5.3-chat-latest"` - - `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.2"` - The annotations of the text output. + - `"gpt-5.2-2025-12-11"` - - `FileCitation object { file_id, filename, index, type }` + - `"gpt-5.2-chat-latest"` - A citation to a file. + - `"gpt-5.2-pro"` - - `file_id: string` + - `"gpt-5.2-pro-2025-12-11"` - The ID of the file. + - `"gpt-5.1"` - - `filename: string` + - `"gpt-5.1-2025-11-13"` - The filename of the file cited. + - `"gpt-5.1-codex"` - - `index: number` + - `"gpt-5.1-mini"` - The index of the file in the list of files. + - `"gpt-5.1-chat-latest"` - - `type: "file_citation"` + - `"gpt-5"` - The type of the file citation. Always `file_citation`. + - `"gpt-5-mini"` - - `"file_citation"` + - `"gpt-5-nano"` - - `URLCitation object { end_index, start_index, title, 2 more }` + - `"gpt-5-2025-08-07"` - A citation for a web resource used to generate a model response. + - `"gpt-5-mini-2025-08-07"` - - `end_index: number` + - `"gpt-5-nano-2025-08-07"` - The index of the last character of the URL citation in the message. + - `"gpt-5-chat-latest"` - - `start_index: number` + - `"gpt-4.1"` - The index of the first character of the URL citation in the message. + - `"gpt-4.1-mini"` - - `title: string` + - `"gpt-4.1-nano"` - The title of the web resource. + - `"gpt-4.1-2025-04-14"` - - `type: "url_citation"` + - `"gpt-4.1-mini-2025-04-14"` - The type of the URL citation. Always `url_citation`. + - `"gpt-4.1-nano-2025-04-14"` - - `"url_citation"` + - `"o4-mini"` - - `url: string` + - `"o4-mini-2025-04-16"` - The URL of the web resource. + - `"o3"` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + - `"o3-2025-04-16"` - A citation for a container file used to generate a model response. + - `"o3-mini"` - - `container_id: string` + - `"o3-mini-2025-01-31"` - The ID of the container file. + - `"o1"` - - `end_index: number` + - `"o1-2024-12-17"` - The index of the last character of the container file citation in the message. + - `"o1-preview"` - - `file_id: string` + - `"o1-preview-2024-09-12"` - The ID of the file. + - `"o1-mini"` - - `filename: string` + - `"o1-mini-2024-09-12"` - The filename of the container file cited. + - `"gpt-4o"` - - `start_index: number` + - `"gpt-4o-2024-11-20"` - The index of the first character of the container file citation in the message. + - `"gpt-4o-2024-08-06"` - - `type: "container_file_citation"` + - `"gpt-4o-2024-05-13"` - The type of the container file citation. Always `container_file_citation`. + - `"gpt-4o-audio-preview"` - - `"container_file_citation"` + - `"gpt-4o-audio-preview-2024-10-01"` - - `FilePath object { file_id, index, type }` + - `"gpt-4o-audio-preview-2024-12-17"` - A path to a file. + - `"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"` - - `index: number` + - `"gpt-4o-search-preview"` - The index of the file in the list of files. + - `"gpt-4o-mini-search-preview"` - - `type: "file_path"` + - `"gpt-4o-search-preview-2025-03-11"` - The type of the file path. Always `file_path`. + - `"gpt-4o-mini-search-preview-2025-03-11"` - - `"file_path"` + - `"chatgpt-4o-latest"` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `"codex-mini-latest"` - - `token: string` + - `"gpt-4o-mini"` - - `bytes: array of number` + - `"gpt-4o-mini-2024-07-18"` - - `logprob: number` + - `"gpt-4-turbo"` - - `top_logprobs: array of object { token, bytes, logprob }` + - `"gpt-4-turbo-2024-04-09"` - - `token: string` + - `"gpt-4-0125-preview"` - - `bytes: array of number` + - `"gpt-4-turbo-preview"` - - `logprob: number` + - `"gpt-4-1106-preview"` - - `text: string` + - `"gpt-4-vision-preview"` - The text output from the model. + - `"gpt-4"` - - `type: "output_text"` + - `"gpt-4-0314"` - The type of the output text. Always `output_text`. + - `"gpt-4-0613"` - - `"output_text"` + - `"gpt-4-32k"` - - `BetaResponseOutputRefusal object { refusal, type }` + - `"gpt-4-32k-0314"` - A refusal from the model. + - `"gpt-4-32k-0613"` - - `refusal: string` + - `"gpt-3.5-turbo"` - The refusal explanation from the model. + - `"gpt-3.5-turbo-16k"` - - `type: "refusal"` + - `"gpt-3.5-turbo-0301"` - The type of the refusal. Always `refusal`. + - `"gpt-3.5-turbo-0613"` - - `"refusal"` + - `"gpt-3.5-turbo-1106"` - - `role: "assistant"` + - `"gpt-3.5-turbo-0125"` - The role of the output message. Always `assistant`. + - `"gpt-3.5-turbo-16k-0613"` - - `"assistant"` + - `"o1-pro"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"o1-pro-2025-03-19"` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `"o3-pro"` - - `"in_progress"` + - `"o3-pro-2025-06-10"` - - `"completed"` + - `"o3-deep-research"` - - `"incomplete"` + - `"o3-deep-research-2025-06-26"` - - `type: "message"` + - `"o4-mini-deep-research"` - The type of the output message. Always `message`. + - `"o4-mini-deep-research-2025-06-26"` - - `"message"` + - `"computer-use-preview"` - - `agent: optional object { agent_name }` + - `"computer-use-preview-2025-03-11"` - The agent that produced this item. + - `"gpt-5-codex"` - - `agent_name: string` + - `"gpt-5-pro"` - The canonical name of the agent that produced this item. + - `"gpt-5-pro-2025-10-06"` - - `phase: optional "commentary" or "final_answer"` + - `"gpt-5.1-codex-max"` - 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. + - `string` - - `"commentary"` + - `object: "response"` - - `"final_answer"` + The object type of this resource - always set to `response`. + + - `"response"` + + - `output: array of BetaResponseOutputItem` + + An array of content items generated by the model. + + - 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. + + - `BetaResponseOutputMessage object { id, content, role, 4 more }` + + An output message from the model. - `FileSearchCall object { id, queries, status, 3 more }` @@ -127631,36 +125025,66 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The text that was retrieved from the file. - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + - `FunctionCall object { arguments, call_id, name, 6 more }` - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `id: string` + - `arguments: string` - The unique ID of the computer call. + A JSON string of the arguments to pass to the function. - `call_id: string` - An identifier used when responding to the tool call with output. + The unique ID of the function tool call generated by the model. - - `pending_safety_checks: array of object { id, code, message }` + - `name: string` - The pending safety checks for the computer call. + The name of the function to run. - - `id: string` + - `type: "function_call"` - The ID of the pending safety check. + The type of the function tool call. Always `function_call`. - - `code: optional string` + - `"function_call"` - The type of the pending safety check. + - `id: optional string` - - `message: optional string` + The unique ID of the function tool call. - Details about the pending safety check. + - `agent: optional object { agent_name }` - - `status: "in_progress" or "completed" or "incomplete"` + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + + - `namespace: optional string` + + The namespace of the function to run. + + - `status: optional "in_progress" or "completed" or "incomplete"` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -127671,247 +125095,273 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `type: "computer_call"` + - `FunctionCallOutput object { id, call_id, output, 5 more }` - The type of the computer call. Always `computer_call`. + - `id: string` - - `"computer_call"` + The unique ID of the function call tool output. - - `action: optional BetaComputerAction` + - `call_id: string` - A click action. + The unique ID of the function tool call generated by the model. - - `Click object { button, type, x, 2 more }` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - A click action. + The output from the function call generated by your code. + Can be a string or an list of output content. - - `button: "left" or "right" or "wheel" or 2 more` + - `StringOutput = string` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + A string of the output of the function call. - - `"left"` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `"right"` + Text, image, or file output of the function call. - - `"wheel"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `"back"` + A text input to the model. - - `"forward"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `type: "click"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - Specifies the event type. For a click action, this property is always `click`. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `"click"` + A file input to the model. - - `x: number` + - `status: "in_progress" or "completed" or "incomplete"` - The x-coordinate where the click occurred. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `y: number` + - `"in_progress"` - The y-coordinate where the click occurred. + - `"completed"` - - `keys: optional array of string` + - `"incomplete"` - The keys being held while clicking. + - `type: "function_call_output"` - - `DoubleClick object { keys, type, x, y }` + The type of the function tool call output. Always `function_call_output`. - A double click action. + - `"function_call_output"` - - `keys: array of string` + - `agent: optional object { agent_name }` - The keys being held while double-clicking. + The agent that produced this item. - - `type: "double_click"` + - `agent_name: string` - Specifies the event type. For a double click action, this property is always set to `double_click`. + The canonical name of the agent that produced this item. - - `"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"` + - `AgentMessage object { id, author, content, 3 more }` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `id: string` - - `"drag"` + The unique ID of the agent message. - - `keys: optional array of string` + - `author: string` - The keys being held while dragging the mouse. + The sending agent identity. - - `Keypress object { keys, type }` + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - A collection of keypresses the model would like to perform. + Encrypted content sent between agents. - - `keys: array of string` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + A text input to the model. - - `type: "keypress"` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + A text output from the model. - - `"keypress"` + - `Text object { text, type }` - - `Move object { type, x, y, keys }` + A text content. - A mouse move action. + - `text: string` - - `type: "move"` + - `type: "text"` - Specifies the event type. For a move action, this property is always set to `move`. + - `"text"` - - `"move"` + - `SummaryText object { text, type }` - - `x: number` + A summary text from the model. - The x-coordinate to move to. + - `text: string` - - `y: number` + A summary of the reasoning output from the model so far. - The y-coordinate to move to. + - `type: "summary_text"` - - `keys: optional array of string` + The type of the object. Always `summary_text`. - The keys being held while moving the mouse. + - `"summary_text"` - - `Screenshot object { type }` + - `ReasoningText object { text, type }` - A screenshot action. + Reasoning text from the model. - - `type: "screenshot"` + - `text: string` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + The reasoning text from the model. - - `"screenshot"` + - `type: "reasoning_text"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + The type of the reasoning text. Always `reasoning_text`. - A scroll action. + - `"reasoning_text"` - - `scroll_x: number` + - `BetaResponseOutputRefusal object { refusal, type }` - The horizontal scroll distance. + A refusal from the model. - - `scroll_y: number` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - The vertical scroll distance. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `type: "scroll"` + - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + A screenshot of a computer. - - `"scroll"` + - `detail: "low" or "high" or "auto" or "original"` - - `x: number` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The x-coordinate where the scroll occurred. + - `"low"` - - `y: number` + - `"high"` - The y-coordinate where the scroll occurred. + - `"auto"` - - `keys: optional array of string` + - `"original"` - The keys being held while scrolling. + - `file_id: string` - - `Type object { text, type }` + The identifier of an uploaded file that contains the screenshot. - An action to type in text. + - `image_url: string` - - `text: string` + The URL of the screenshot image. - The text to type. + - `type: "computer_screenshot"` - - `type: "type"` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - Specifies the event type. For a type action, this property is always set to `type`. + - `"computer_screenshot"` - - `"type"` + - `prompt_cache_breakpoint: optional object { mode }` - - `Wait object { 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. - A wait action. + - `mode: "explicit"` - - `type: "wait"` + The breakpoint mode. Always `explicit`. - Specifies the event type. For a wait action, this property is always set to `wait`. + - `"explicit"` - - `"wait"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `actions: optional BetaComputerActionList` + A file input to the model. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `EncryptedContent object { encrypted_content, type }` - - `Click object { button, type, x, 2 more }` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - A click action. + - `encrypted_content: string` - - `DoubleClick object { keys, type, x, y }` + Opaque encrypted content. - A double click action. + - `type: "encrypted_content"` - - `Drag object { path, type, keys }` + The type of the input item. Always `encrypted_content`. - A drag action. + - `"encrypted_content"` - - `Keypress object { keys, type }` + - `recipient: string` - A collection of keypresses the model would like to perform. + The destination agent identity. - - `Move object { type, x, y, keys }` + - `type: "agent_message"` - A mouse move action. + The type of the item. Always `agent_message`. - - `Screenshot object { type }` + - `"agent_message"` - A screenshot action. + - `agent: optional object { agent_name }` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + The agent that produced this item. - A scroll action. + - `agent_name: string` - - `Type object { text, type }` + The canonical name of the agent that produced this item. - An action to type in text. + - `MultiAgentCall object { id, action, arguments, 3 more }` - - `Wait object { type }` + - `id: string` - A wait action. + The unique ID of the multi-agent call item. + + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + + The multi-agent action to execute. + + - `"spawn_agent"` + + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` + + - `arguments: string` + + The JSON string of arguments generated for the action. + + - `call_id: string` + + The unique ID linking this call to its output. + + - `type: "multi_agent_call"` + + The type of the multi-agent call. Always `multi_agent_call`. + + - `"multi_agent_call"` - `agent: optional object { agent_name }` @@ -127921,58 +125371,55 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `ComputerCallOutput object { call_id, output, type, 4 more }` - - The output of a computer tool call. + - `MultiAgentCallOutput object { id, action, call_id, 3 more }` - - `call_id: string` + - `id: string` - The ID of the computer tool call that produced the output. + The unique ID of the multi-agent call output item. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - A computer screenshot image used with the computer use tool. + The multi-agent action that produced this result. - - `type: "computer_screenshot"` + - `"spawn_agent"` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `"interrupt_agent"` - - `"computer_screenshot"` + - `"list_agents"` - - `file_id: optional string` + - `"send_message"` - The identifier of an uploaded file that contains the screenshot. + - `"followup_task"` - - `image_url: optional string` + - `"wait_agent"` - The URL of the screenshot image. + - `call_id: string` - - `type: "computer_call_output"` + The unique ID of the multi-agent call. - The type of the computer tool call output. Always `computer_call_output`. + - `output: array of BetaResponseOutputText` - - `"computer_call_output"` + Text output returned by the multi-agent action. - - `id: optional string` + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - The ID of the computer tool call output. + The annotations of the text output. - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - The safety checks reported by the API that have been acknowledged by the developer. + - `text: string` - - `id: string` + The text output from the model. - The ID of the pending safety check. + - `type: "output_text"` - - `code: optional string` + The type of the output text. Always `output_text`. - The type of the pending safety check. + - `type: "multi_agent_call_output"` - - `message: optional string` + The type of the multi-agent result. Always `multi_agent_call_output`. - Details about the pending safety check. + - `"multi_agent_call_output"` - `agent: optional object { agent_name }` @@ -127982,16 +125429,6 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - `WebSearchCall object { id, action, status, 2 more }` The results of a web search tool call. See the @@ -128096,66 +125533,36 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `FunctionCall object { arguments, call_id, name, 6 more }` + - `ComputerCall object { id, call_id, pending_safety_checks, 5 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. - - - `name: string` - - The name of the function to run. - - - `type: "function_call"` - - The type of the function tool call. Always `function_call`. - - - `"function_call"` - - - `id: optional string` - - The unique ID of the function tool call. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. - - - `Direct object { type }` - - - `type: "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` - - `"program"` + The type of the pending safety check. - - `namespace: optional string` + - `message: optional string` - The namespace of the function to run. + Details about the pending safety check. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `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. @@ -128166,145 +125573,20 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `FunctionCallOutput object { call_id, output, type, 4 more }` - - The output of a function tool call. - - - `call_id: string` - - The unique ID of the function tool call generated by the model. - - - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - - Text, image, or file output of the function tool call. - - - `string` - - A JSON string of the output of the function tool call. - - - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - - An array of content outputs (text, image, file) for the function tool call. - - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `text: string` - - The text input to the model. - - - `type: "input_text"` - - The type of the input item. Always `input_text`. - - - `"input_text"` - - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `"explicit"` - - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](/docs/guides/vision) - - - `type: "input_image"` - - The type of the input item. Always `input_image`. - - - `"input_image"` - - - `detail: optional "low" or "high" or "auto" or "original"` - - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - - `"low"` - - - `"high"` - - - `"auto"` - - - `"original"` - - - `file_id: optional string` - - The ID of the file to be sent to the model. - - - `image_url: optional string` - - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - - `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"` - - - `BetaResponseInputFileContent 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`. + - `type: "computer_call"` - - `"explicit"` + The type of the computer call. Always `computer_call`. - - `type: "function_call_output"` + - `"computer_call"` - The type of the function tool call output. Always `function_call_output`. + - `action: optional BetaComputerAction` - - `"function_call_output"` + A click action. - - `id: optional string` + - `actions: optional BetaComputerActionList` - The unique ID of the function 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. - `agent: optional object { agent_name }` @@ -128314,87 +125596,55 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `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 }` + - `ComputerCallOutput object { id, call_id, output, 5 more }` - - `caller_id: string` + - `id: string` - The call ID of the program item that produced this tool call. + The unique ID of the computer call tool output. - - `type: "program"` + - `call_id: string` - The caller type. Always `program`. + The ID of the computer tool call that produced the output. - - `"program"` + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `status: optional "in_progress" or "completed" or "incomplete"` + A computer screenshot image used with the computer use tool. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - - `"in_progress"` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - `"completed"` - `"incomplete"` - - `AgentMessage object { author, content, recipient, 3 more }` - - A message routed between agents. - - - `author: string` - - The sending agent identity. - - - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - - Plaintext, image, or encrypted content sent between agents. - - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](/docs/guides/vision) - - - `EncryptedContent object { encrypted_content, type }` - - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `"failed"` - - `encrypted_content: string` + - `"in_progress"` - Opaque encrypted content. + - `type: "computer_call_output"` - - `type: "encrypted_content"` + The type of the computer tool call output. Always `computer_call_output`. - The type of the input item. Always `encrypted_content`. + - `"computer_call_output"` - - `"encrypted_content"` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `recipient: string` + The safety checks reported by the API that have been acknowledged by the + developer. - The destination agent identity. + - `id: string` - - `type: "agent_message"` + The ID of the pending safety check. - The item type. Always `agent_message`. + - `code: optional string` - - `"agent_message"` + The type of the pending safety check. - - `id: optional string` + - `message: optional string` - The unique ID of this agent message item. + Details about the pending safety check. - `agent: optional object { agent_name }` @@ -128404,41 +125654,40 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `MultiAgentCall object { action, arguments, call_id, 3 more }` - - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - The multi-agent action that was executed. + - `created_by: optional string` - - `"spawn_agent"` + The identifier of the actor that created the item. - - `"interrupt_agent"` + - `Reasoning object { id, summary, type, 4 more }` - - `"list_agents"` + 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). - - `"send_message"` + - `id: string` - - `"followup_task"` + The unique identifier of the reasoning content. - - `"wait_agent"` + - `summary: array of object { text, type }` - - `arguments: string` + Reasoning summary content. - The action arguments as a JSON string. + - `text: string` - - `call_id: string` + A summary of the reasoning output from the model so far. - The unique ID linking this call to its output. + - `type: "summary_text"` - - `type: "multi_agent_call"` + The type of the object. Always `summary_text`. - The item type. Always `multi_agent_call`. + - `"summary_text"` - - `"multi_agent_call"` + - `type: "reasoning"` - - `id: optional string` + The type of the object. Always `reasoning`. - The unique ID of this multi-agent call. + - `"reasoning"` - `agent: optional object { agent_name }` @@ -128448,152 +125697,143 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `MultiAgentCallOutput object { action, call_id, output, 3 more }` - - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - The multi-agent action that produced this result. - - - `"spawn_agent"` - - - `"interrupt_agent"` + - `content: optional array of object { text, type }` - - `"list_agents"` + Reasoning text content. - - `"send_message"` + - `text: string` - - `"followup_task"` + The reasoning text from the model. - - `"wait_agent"` + - `type: "reasoning_text"` - - `call_id: string` + The type of the reasoning text. Always `reasoning_text`. - The unique ID of the multi-agent call. + - `"reasoning_text"` - - `output: array of object { text, type, annotations }` + - `encrypted_content: optional string` - Text output returned by the multi-agent action. + 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. - - `text: string` + - `status: optional "in_progress" or "completed" or "incomplete"` - The text content. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `type: "output_text"` + - `"in_progress"` - The content type. Always `output_text`. + - `"completed"` - - `"output_text"` + - `"incomplete"` - - `annotations: optional 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 }` + - `Program object { id, call_id, code, 3 more }` - Citations associated with the text content. + - `id: string` - - `FileCitation object { file_id, filename, index, type }` + The unique ID of the program item. - - `file_id: string` + - `call_id: string` - The ID of the file. + The stable call ID of the program item. - - `filename: string` + - `code: string` - The filename of the file cited. + The JavaScript source executed by programmatic tool calling. - - `index: number` + - `fingerprint: string` - The index of the file in the list of files. + Opaque program replay fingerprint that must be round-tripped. - - `type: "file_citation"` + - `type: "program"` - The citation type. Always `file_citation`. + The type of the item. Always `program`. - - `"file_citation"` + - `"program"` - - `URLCitation object { end_index, start_index, title, 2 more }` + - `agent: optional object { agent_name }` - - `end_index: number` + The agent that produced this item. - The index of the last character of the citation in the message. + - `agent_name: string` - - `start_index: number` + The canonical name of the agent that produced this item. - The index of the first character of the citation in the message. + - `ProgramOutput object { id, call_id, result, 3 more }` - - `title: string` + - `id: string` - The title of the cited resource. + The unique ID of the program output item. - - `type: "url_citation"` + - `call_id: string` - The citation type. Always `url_citation`. + The call ID of the program item. - - `"url_citation"` + - `result: string` - - `url: string` + The result produced by the program item. - The URL of the cited resource. + - `status: "completed" or "incomplete"` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + The terminal status of the program output item. - - `container_id: string` + - `"completed"` - The ID of the container. + - `"incomplete"` - - `end_index: number` + - `type: "program_output"` - The index of the last character of the citation in the message. + The type of the item. Always `program_output`. - - `file_id: string` + - `"program_output"` - The ID of the container file. + - `agent: optional object { agent_name }` - - `filename: string` + The agent that produced this item. - The filename of the container file cited. + - `agent_name: string` - - `start_index: number` + The canonical name of the agent that produced this item. - The index of the first character of the citation in the message. + - `ToolSearchCall object { id, arguments, call_id, 5 more }` - - `type: "container_file_citation"` + - `id: string` - The citation type. Always `container_file_citation`. + The unique ID of the tool search call item. - - `"container_file_citation"` + - `arguments: unknown` - - `type: "multi_agent_call_output"` + Arguments used for the tool search call. - The item type. Always `multi_agent_call_output`. + - `call_id: string` - - `"multi_agent_call_output"` + The unique ID of the tool search call generated by the model. - - `id: optional string` + - `execution: "server" or "client"` - The unique ID of this multi-agent call output. + Whether tool search was executed by the server or by the client. - - `agent: optional object { agent_name }` + - `"server"` - The agent that produced this item. + - `"client"` - - `agent_name: string` + - `status: "in_progress" or "completed" or "incomplete"` - The canonical name of the agent that produced this item. + The status of the tool search call item that was recorded. - - `ToolSearchCall object { arguments, type, id, 4 more }` + - `"in_progress"` - - `arguments: unknown` + - `"completed"` - The arguments supplied to the tool search call. + - `"incomplete"` - `type: "tool_search_call"` - The item type. Always `tool_search_call`. + The type of the item. Always `tool_search_call`. - `"tool_search_call"` - - `id: optional string` - - The unique ID of this tool search call. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -128602,11 +125842,21 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `call_id: optional string` + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `ToolSearchOutput object { id, call_id, execution, 5 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: optional "server" or "client"` + - `execution: "server" or "client"` Whether tool search was executed by the server or by the client. @@ -128614,9 +125864,9 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"client"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `status: "in_progress" or "completed" or "incomplete"` - The status of the tool search call. + The status of the tool search output item that was recorded. - `"in_progress"` @@ -128624,11 +125874,9 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `ToolSearchOutput object { tools, type, id, 4 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. + The loaded tool definitions returned by tool search. - `Function object { name, parameters, strict, 5 more }` @@ -129149,40 +126397,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `BetaContainerNetworkPolicyDisabled object { type }` - - `type: "disabled"` - - Disable outbound network access. Always `disabled`. - - - `"disabled"` - - `BetaContainerNetworkPolicyAllowlist 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 BetaContainerNetworkPolicyDomainSecret` - - 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`. @@ -129363,128 +126579,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `BetaContainerAuto 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 BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - Network access policy for the container. - - - `BetaContainerNetworkPolicyDisabled object { type }` - - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - - `skills: optional array of BetaSkillReference or BetaInlineSkill` - - An optional list of skills referenced by id or inline data. - - - `BetaSkillReference 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. - - - `BetaInlineSkill object { description, name, source, type }` - - - `description: string` - - The description of the skill. - - - `name: string` - - The name of the skill. - - - `source: BetaInlineSkillSource` - - 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"` - - `BetaLocalEnvironment object { type, skills }` - - `type: "local"` - - Use a local computer environment. - - - `"local"` - - - `skills: optional array of BetaLocalSkill` - - 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. - - `BetaContainerReference 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) @@ -129771,14 +126869,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "tool_search_output"` - The item type. Always `tool_search_output`. + The type of the item. Always `tool_search_output`. - `"tool_search_output"` - - `id: optional string` - - The unique ID of this tool search output. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -129787,39 +126881,39 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `call_id: optional string` - - The unique ID of the tool search call generated by the model. + - `created_by: optional string` - - `execution: optional "server" or "client"` + The identifier of the actor that created the item. - Whether tool search was executed by the server or by the client. + - `AdditionalTools object { id, role, tools, 2 more }` - - `"server"` + - `id: string` - - `"client"` + The unique ID of the additional tools item. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `role: "unknown" or "user" or "assistant" or 5 more` - The status of the tool search output. + The role that provided the additional tools. - - `"in_progress"` + - `"unknown"` - - `"completed"` + - `"user"` - - `"incomplete"` + - `"assistant"` - - `AdditionalTools object { role, tools, type, 2 more }` + - `"system"` - - `role: "developer"` + - `"critic"` - The role that provided the additional tools. Only `developer` is supported. + - `"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` - A list of additional tools made available at this item. + The additional tool definitions made available at this item. - `Function object { name, parameters, strict, 5 more }` @@ -130442,383 +127536,1115 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `output_compression: optional number` - Compression level for the output image. Default: 100. + 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 BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `BetaLocalEnvironment object { type, skills }` + + - `BetaContainerReference 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 object { type } or object { definition, syntax, type }` + + 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 object { type } or object { definition, syntax, type }` + + 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"` + + - `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: "additional_tools"` + + The type of the item. Always `additional_tools`. + + - `"additional_tools"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `Compaction object { id, encrypted_content, type, 2 more }` + + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + + - `id: string` + + The unique ID of the compaction item. + + - `encrypted_content: string` + + The encrypted content that was produced by compaction. + + - `type: "compaction"` + + The type of the item. Always `compaction`. + + - `"compaction"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `ImageGenerationCall object { id, result, status, 2 more }` + + An image generation request made by the model. + + - `id: string` + + The unique ID of the image generation call. + + - `result: string` + + The generated image encoded in base64. + + - `status: "in_progress" or "completed" or "generating" or "failed"` + + The status of the image generation call. + + - `"in_progress"` + + - `"completed"` + + - `"generating"` + + - `"failed"` + + - `type: "image_generation_call"` + + The type of the image generation call. Always `image_generation_call`. + + - `"image_generation_call"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `CodeInterpreterCall object { id, code, container_id, 4 more }` + + A tool call to run code. + + - `id: string` + + The unique ID of the code interpreter tool call. + + - `code: string` + + The code to run, or null if not available. + + - `container_id: string` + + The ID of the container used to run the code. + + - `outputs: array of object { logs, type } or object { type, url }` + + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. + + - `Logs object { logs, type }` + + The logs output from the code interpreter. + + - `logs: string` + + The logs output from the code interpreter. + + - `type: "logs"` + + The type of the output. Always `logs`. + + - `"logs"` + + - `Image object { type, url }` + + The image output from the code interpreter. + + - `type: "image"` + + The type of the output. Always `image`. + + - `"image"` + + - `url: string` + + The URL of the image output from the code interpreter. + + - `status: "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"interpreting"` + + - `"failed"` + + - `type: "code_interpreter_call"` + + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `"code_interpreter_call"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `LocalShellCall object { id, action, call_id, 3 more }` + + A tool call to run a command on the local shell. + + - `id: string` + + The unique ID of the local shell call. + + - `action: object { command, env, type, 3 more }` + + Execute a shell command on the server. + + - `command: array of string` + + The command to run. + + - `env: map[string]` + + Environment variables to set for the command. + + - `type: "exec"` + + The type of the local shell action. Always `exec`. + + - `"exec"` + + - `timeout_ms: optional number` + + Optional timeout in milliseconds for the command. + + - `user: optional string` + + Optional user to run the command as. + + - `working_directory: optional string` + + Optional working directory to run the command in. + + - `call_id: string` + + The unique ID of the local shell tool call generated by the model. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the local shell call. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "local_shell_call"` + + The type of the local shell call. Always `local_shell_call`. + + - `"local_shell_call"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `LocalShellCallOutput object { id, output, type, 2 more }` + + The output of a local shell tool call. + + - `id: string` + + The unique ID of the local shell tool call generated by the model. + + - `output: string` + + A JSON string of the output of the local shell tool call. + + - `type: "local_shell_call_output"` + + The type of the local shell tool call output. Always `local_shell_call_output`. + + - `"local_shell_call_output"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `ShellCall object { id, action, call_id, 6 more }` + + 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 shell tool call generated by the model. + + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + + Represents the use of a local environment to perform shell actions. + + - `BetaResponseLocalEnvironment object { type }` + + Represents the use of a local environment to perform shell actions. + + - `type: "local"` + + The environment type. Always `local`. + + - `"local"` + + - `BetaResponseContainerReference 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"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + + - `created_by: optional string` + + The ID of the entity that created this tool call. + + - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` + + The output of a shell tool call that was emitted. + + - `id: string` - - `output_format: optional "png" or "webp" or "jpeg"` + The unique ID of the shell call output. Populated when this item is returned via API. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `call_id: string` - - `"png"` + The unique ID of the shell tool call generated by the model. - - `"webp"` + - `max_output_length: number` - - `"jpeg"` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `partial_images: optional number` + - `output: array of object { outcome, stderr, stdout, created_by }` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + An array of shell call output contents - - `quality: optional "low" or "medium" or "high" or "auto"` + - `outcome: object { type } or object { exit_code, type }` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - - `"low"` + - `Timeout object { type }` - - `"medium"` + Indicates that the shell call exceeded its configured time limit. - - `"high"` + - `type: "timeout"` - - `"auto"` + The outcome type. Always `timeout`. - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `"timeout"` - 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`. + - `Exit object { exit_code, type }` - - `string` + Indicates that the shell commands finished and returned an exit code. - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `exit_code: number` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + Exit code from the shell process. - - `"1024x1024"` + - `type: "exit"` - - `"1024x1536"` + The outcome type. Always `exit`. - - `"1536x1024"` + - `"exit"` - - `"auto"` + - `stderr: string` - - `LocalShell object { type }` + The standard error output that was captured. - A tool that allows the model to execute shell commands in a local environment. + - `stdout: string` - - `type: "local_shell"` + The standard output that was captured. - The type of the local shell tool. Always `local_shell`. + - `created_by: optional string` - - `"local_shell"` + The identifier of the actor that created the item. - - `Shell object { type, allowed_callers, environment }` + - `status: "in_progress" or "completed" or "incomplete"` - A tool that allows the model to execute shell commands. + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `type: "shell"` + - `"in_progress"` - The type of the shell tool. Always `shell`. + - `"completed"` - - `"shell"` + - `"incomplete"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "shell_call_output"` - The tool invocation context(s). + The type of the shell call output. Always `shell_call_output`. - - `"direct"` + - `"shell_call_output"` - - `"programmatic"` + - `agent: optional object { agent_name }` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + The agent that produced this item. - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `agent_name: string` - - `BetaLocalEnvironment object { type, skills }` + The canonical name of the agent that produced this item. - - `BetaContainerReference object { container_id, type }` + - `caller: optional object { type } or object { caller_id, type }` - - `Custom object { name, type, allowed_callers, 3 more }` + The execution context that produced this tool call. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `Direct object { type }` - - `name: string` + - `type: "direct"` - The name of the custom tool, used to identify it in tool calls. + - `"direct"` - - `type: "custom"` + - `Program object { caller_id, type }` - The type of the custom tool. Always `custom`. + - `caller_id: string` - - `"custom"` + The call ID of the program item that produced this tool call. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "program"` - The tool invocation context(s). + - `"program"` - - `"direct"` + - `created_by: optional string` - - `"programmatic"` + The identifier of the actor that created the item. - - `defer_loading: optional boolean` + - `ApplyPatchCall object { id, call_id, operation, 5 more }` - Whether this tool should be deferred and discovered via tool search. + A tool call that applies file diffs by creating, deleting, or updating files. - - `description: optional string` + - `id: string` - Optional description of the custom tool, used to provide more context. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `format: optional object { type } or object { definition, syntax, type }` + - `call_id: string` - The input format for the custom tool. Default is unconstrained text. + The unique ID of the apply patch tool call generated by the model. - - `Text object { type }` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - Unconstrained free-form text. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `type: "text"` + - `CreateFile object { diff, path, type }` - Unconstrained text format. Always `text`. + Instruction describing how to create a file via the apply_patch tool. - - `"text"` + - `diff: string` - - `Grammar object { definition, syntax, type }` + Diff to apply. - A grammar defined by the user. + - `path: string` - - `definition: string` + Path of the file to create. - The grammar definition. + - `type: "create_file"` - - `syntax: "lark" or "regex"` + Create a new file with the provided diff. - The syntax of the grammar definition. One of `lark` or `regex`. + - `"create_file"` - - `"lark"` + - `DeleteFile object { path, type }` - - `"regex"` + Instruction describing how to delete a file via the apply_patch tool. - - `type: "grammar"` + - `path: string` - Grammar format. Always `grammar`. + Path of the file to delete. - - `"grammar"` + - `type: "delete_file"` - - `Namespace object { description, name, tools, type }` + Delete the specified file. - Groups function/custom tools under a shared namespace. + - `"delete_file"` - - `description: string` + - `UpdateFile object { diff, path, type }` - A description of the namespace shown to the model. + Instruction describing how to update a file via the apply_patch tool. - - `name: string` + - `diff: string` - The namespace name used in tool calls (for example, `crm`). + Diff to apply. - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `path: string` - The function/custom tools available inside this namespace. + Path of the file to update. - - `Function object { name, type, allowed_callers, 5 more }` + - `type: "update_file"` - - `name: string` + Update an existing file with the provided diff. - - `type: "function"` + - `"update_file"` - - `"function"` + - `status: "in_progress" or "completed"` - - `allowed_callers: optional array of "direct" or "programmatic"` + The status of the apply patch tool call. One of `in_progress` or `completed`. - The tool invocation context(s). + - `"in_progress"` - - `"direct"` + - `"completed"` - - `"programmatic"` + - `type: "apply_patch_call"` - - `defer_loading: optional boolean` + The type of the item. Always `apply_patch_call`. - Whether this function should be deferred and discovered via tool search. + - `"apply_patch_call"` - - `description: optional string` + - `agent: optional object { agent_name }` - - `output_schema: optional map[unknown]` + The agent that produced this item. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `agent_name: string` - - `parameters: optional unknown` + The canonical name of the agent that produced this item. - - `strict: optional boolean` + - `caller: optional object { type } or object { caller_id, type }` - 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 execution context that produced this tool call. - - `Custom object { name, type, allowed_callers, 3 more }` + - `Direct object { type }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `type: "direct"` - - `name: string` + - `"direct"` - The name of the custom tool, used to identify it in tool calls. + - `Program object { caller_id, type }` - - `type: "custom"` + - `caller_id: string` - The type of the custom tool. Always `custom`. + The call ID of the program item that produced this tool call. - - `"custom"` + - `type: "program"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"program"` - The tool invocation context(s). + - `created_by: optional string` - - `"direct"` + The ID of the entity that created this tool call. - - `"programmatic"` + - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` - - `defer_loading: optional boolean` + The output emitted by an apply patch tool call. - Whether this tool should be deferred and discovered via tool search. + - `id: string` - - `description: optional string` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - Optional description of the custom tool, used to provide more context. + - `call_id: string` - - `format: optional object { type } or object { definition, syntax, type }` + The unique ID of the apply patch tool call generated by the model. - The input format for the custom tool. Default is unconstrained text. + - `status: "completed" or "failed"` - - `Text object { type }` + The status of the apply patch tool call output. One of `completed` or `failed`. - Unconstrained free-form text. + - `"completed"` - - `type: "text"` + - `"failed"` - Unconstrained text format. Always `text`. + - `type: "apply_patch_call_output"` - - `"text"` + The type of the item. Always `apply_patch_call_output`. - - `Grammar object { definition, syntax, type }` + - `"apply_patch_call_output"` - A grammar defined by the user. + - `agent: optional object { agent_name }` - - `definition: string` + The agent that produced this item. - The grammar definition. + - `agent_name: string` - - `syntax: "lark" or "regex"` + The canonical name of the agent that produced this item. - The syntax of the grammar definition. One of `lark` or `regex`. + - `caller: optional object { type } or object { caller_id, type }` - - `"lark"` + The execution context that produced this tool call. - - `"regex"` + - `Direct object { type }` - - `type: "grammar"` + - `type: "direct"` - Grammar format. Always `grammar`. + - `"direct"` - - `"grammar"` + - `Program object { caller_id, type }` - - `type: "namespace"` + - `caller_id: string` - The type of the tool. Always `namespace`. + The call ID of the program item that produced this tool call. - - `"namespace"` + - `type: "program"` - - `ToolSearch object { type, description, execution, parameters }` + - `"program"` - Hosted or BYOT tool search configuration for deferred tools. + - `created_by: optional string` - - `type: "tool_search"` + The ID of the entity that created this tool call output. - The type of the tool. Always `tool_search`. + - `output: optional string` - - `"tool_search"` + Optional textual output returned by the apply patch tool. - - `description: optional string` + - `McpCall object { id, arguments, name, 7 more }` - Description shown to the model for a client-executed tool search tool. + An invocation of a tool on an MCP server. - - `execution: optional "server" or "client"` + - `id: string` - Whether tool search is executed by the server or by the client. + The unique ID of the tool call. - - `"server"` + - `arguments: string` - - `"client"` + A JSON string of the arguments passed to the tool. - - `parameters: optional unknown` + - `name: string` - Parameter schema for a client-executed tool search tool. + The name of the tool that was run. - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `server_label: 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 label of the MCP server running the tool. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `type: "mcp_call"` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + The type of the item. Always `mcp_call`. - - `"web_search_preview"` + - `"mcp_call"` - - `"web_search_preview_2025_03_11"` + - `agent: optional object { agent_name }` - - `search_content_types: optional array of "text" or "image"` + The agent that produced this item. - - `"text"` + - `agent_name: string` - - `"image"` + The canonical name of the agent that produced this item. - - `search_context_size: optional "low" or "medium" or "high"` + - `approval_request_id: 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. + 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. - - `"low"` + - `error: optional string` - - `"medium"` + The error from the tool call, if any. - - `"high"` + - `output: optional string` - - `user_location: optional object { type, city, country, 2 more }` + The output from the tool call. - The user's location. + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `type: "approximate"` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - The type of location approximation. Always `approximate`. + - `"in_progress"` - - `"approximate"` + - `"completed"` - - `city: optional string` + - `"incomplete"` - Free text input for the city of the user, e.g. `San Francisco`. + - `"calling"` - - `country: optional string` + - `"failed"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `McpListTools object { id, server_label, tools, 3 more }` - - `region: optional string` + A list of tools available on an MCP server. - Free text input for the region of the user, e.g. `California`. + - `id: string` - - `timezone: optional string` + The unique ID of the list. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `server_label: string` - - `ApplyPatch object { type, allowed_callers }` + The label of the MCP server. - Allows the assistant to create, delete, or update files using unified diffs. + - `tools: array of object { input_schema, name, annotations, description }` - - `type: "apply_patch"` + The tools available on the server. - The type of the tool. Always `apply_patch`. + - `input_schema: unknown` - - `"apply_patch"` + The JSON schema describing the tool's input. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `name: string` - The tool invocation context(s). + The name of the tool. - - `"direct"` + - `annotations: optional unknown` - - `"programmatic"` + Additional annotations about the tool. - - `type: "additional_tools"` + - `description: optional string` - The item type. Always `additional_tools`. + The description of the tool. - - `"additional_tools"` + - `type: "mcp_list_tools"` - - `id: optional string` + The type of the item. Always `mcp_list_tools`. - The unique ID of this additional tools item. + - `"mcp_list_tools"` - `agent: optional object { agent_name }` @@ -130828,36 +128654,35 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `Reasoning object { id, summary, type, 4 more }` + - `error: optional 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). + Error message if the server could not list tools. - - `id: string` + - `McpApprovalRequest object { id, arguments, name, 3 more }` - The unique identifier of the reasoning content. + A request for human approval of a tool invocation. - - `summary: array of object { text, type }` + - `id: string` - Reasoning summary content. + The unique ID of the approval request. - - `text: string` + - `arguments: string` - A summary of the reasoning output from the model so far. + A JSON string of arguments for the tool. - - `type: "summary_text"` + - `name: string` - The type of the object. Always `summary_text`. + The name of the tool to run. - - `"summary_text"` + - `server_label: string` - - `type: "reasoning"` + The label of the MCP server making the request. - The type of the object. Always `reasoning`. + - `type: "mcp_approval_request"` - - `"reasoning"` + The type of the item. Always `mcp_approval_request`. + + - `"mcp_approval_request"` - `agent: optional object { agent_name }` @@ -130867,54 +128692,27 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `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"` + - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` - - `"incomplete"` + A response to an MCP approval request. - - `Compaction object { encrypted_content, type, id, agent }` + - `id: string` - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + The unique ID of the approval response - - `encrypted_content: string` + - `approval_request_id: string` - The encrypted content of the compaction summary. + The ID of the approval request being answered. - - `type: "compaction"` + - `approve: boolean` - The type of the item. Always `compaction`. + Whether the request was approved. - - `"compaction"` + - `type: "mcp_approval_response"` - - `id: optional string` + The type of the item. Always `mcp_approval_response`. - The ID of the compaction item. + - `"mcp_approval_response"` - `agent: optional object { agent_name }` @@ -130924,35 +128722,35 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `ImageGenerationCall object { id, result, status, 2 more }` + - `reason: optional string` - An image generation request made by the model. + Optional reason for the decision. - - `id: string` + - `CustomToolCall object { call_id, input, name, 5 more }` - The unique ID of the image generation call. + A call to a custom tool created by the model. - - `result: string` + - `call_id: string` - The generated image encoded in base64. + An identifier used to map this custom tool call to a tool call output. - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `input: string` - The status of the image generation call. + The input for the custom tool call generated by the model. - - `"in_progress"` + - `name: string` - - `"completed"` + The name of the custom tool being called. - - `"generating"` + - `type: "custom_tool_call"` - - `"failed"` + The type of the custom tool call. Always `custom_tool_call`. - - `type: "image_generation_call"` + - `"custom_tool_call"` - The type of the image generation call. Always `image_generation_call`. + - `id: optional string` - - `"image_generation_call"` + The unique ID of the custom tool call in the OpenAI platform. - `agent: optional object { agent_name }` @@ -130962,58 +128760,69 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `CodeInterpreterCall object { id, code, container_id, 4 more }` + - `caller: optional object { type } or object { caller_id, type }` - A tool call to run code. + The execution context that produced this tool call. - - `id: string` + - `Direct object { type }` - The unique ID of the code interpreter tool call. + - `type: "direct"` - - `code: string` + - `"direct"` - The code to run, or null if not available. + - `Program object { caller_id, type }` - - `container_id: string` + - `caller_id: string` - The ID of the container used to run the code. + The call ID of the program item that produced this tool call. - - `outputs: array of object { logs, type } or object { type, url }` + - `type: "program"` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `"program"` - - `Logs object { logs, type }` + - `namespace: optional string` - The logs output from the code interpreter. + The namespace of the custom tool being called. - - `logs: string` + - `CustomToolCallOutput object { id, call_id, output, 5 more }` - The logs output from the code interpreter. + - `id: string` - - `type: "logs"` + The unique ID of the custom tool call output item. - The type of the output. Always `logs`. + - `call_id: string` - - `"logs"` + The call ID, used to map this custom tool call output to a custom tool call. - - `Image object { type, url }` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The image output from the code interpreter. + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `type: "image"` + - `StringOutput = string` - The type of the output. Always `image`. + A string of the output of the custom tool call. - - `"image"` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `url: string` + Text, image, or file output of the custom tool call. - The URL of the image output from the code interpreter. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + A text input to the model. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](/docs/guides/vision). + + - `BetaResponseInputFile 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"` @@ -131021,15 +128830,11 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `"interpreting"` - - - `"failed"` - - - `type: "code_interpreter_call"` + - `type: "custom_tool_call_output"` - The type of the code interpreter tool call. Always `code_interpreter_call`. + The type of the custom tool call output. Always `custom_tool_call_output`. - - `"code_interpreter_call"` + - `"custom_tool_call_output"` - `agent: optional object { agent_name }` @@ -131039,1598 +128844,1763 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `LocalShellCall object { id, action, call_id, 3 more }` + - `caller: optional object { type } or object { caller_id, type }` - A tool call to run a command on the local shell. + The execution context that produced this tool call. - - `id: string` + - `Direct object { type }` - The unique ID of the local shell call. + - `type: "direct"` - - `action: object { command, env, type, 3 more }` + The caller type. Always `direct`. - Execute a shell command on the server. + - `"direct"` - - `command: array of string` + - `Program object { caller_id, type }` - The command to run. + - `caller_id: string` - - `env: map[string]` + The call ID of the program item that produced this tool call. - Environment variables to set for the command. + - `type: "program"` - - `type: "exec"` + The caller type. Always `program`. - The type of the local shell action. Always `exec`. + - `"program"` - - `"exec"` + - `created_by: optional string` - - `timeout_ms: optional number` + The identifier of the actor that created the item. - Optional timeout in milliseconds for the command. + - `parallel_tool_calls: boolean` - - `user: optional string` + Whether to allow the model to run tool calls in parallel. - Optional user to run the command as. + - `temperature: number` - - `working_directory: optional 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. - Optional working directory to run the command in. + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - - `call_id: 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 unique ID of the local shell tool call generated by the model. + - `BetaToolChoiceOptions = "none" or "auto" or "required"` - - `status: "in_progress" or "completed" or "incomplete"` + Controls which (if any) tool is called by the model. - The status of the local shell call. + `none` means the model will not call any tool and instead generates a message. - - `"in_progress"` + `auto` means the model can pick between generating a message or calling one or + more tools. - - `"completed"` + `required` means the model must call one or more tools. - - `"incomplete"` + - `"none"` - - `type: "local_shell_call"` + - `"auto"` - The type of the local shell call. Always `local_shell_call`. + - `"required"` - - `"local_shell_call"` + - `BetaToolChoiceAllowed object { mode, tools, type }` - - `agent: optional object { agent_name }` + Constrains the tools available to the model to a pre-defined set. - The agent that produced this item. + - `mode: "auto" or "required"` - - `agent_name: string` + Constrains the tools available to the model to a pre-defined set. - The canonical name of the agent that produced this item. + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `LocalShellCallOutput object { id, output, type, 2 more }` + `required` requires the model to call one or more of the allowed tools. - The output of a local shell tool call. + - `"auto"` - - `id: string` + - `"required"` - The unique ID of the local shell tool call generated by the model. + - `tools: array of map[unknown]` - - `output: string` + A list of tool definitions that the model should be allowed to call. - A JSON string of the output of the local shell tool call. + For the Responses API, the list of tool definitions might look like: - - `type: "local_shell_call_output"` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `type: "allowed_tools"` - - `"local_shell_call_output"` + Allowed tool configuration type. Always `allowed_tools`. - - `agent: optional object { agent_name }` + - `"allowed_tools"` - The agent that produced this item. + - `BetaToolChoiceTypes object { type }` - - `agent_name: string` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](/docs/guides/tools). - The canonical name of the agent that produced this item. + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` - - `status: optional "in_progress" or "completed" or "incomplete"` + The type of hosted tool the model should to use. Learn more about + [built-in tools](/docs/guides/tools). - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + Allowed values are: - - `"in_progress"` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `"completed"` + - `"file_search"` - - `"incomplete"` + - `"web_search_preview"` - - `ShellCall object { action, call_id, type, 5 more }` + - `"computer"` - A tool representing a request to execute one or more shell commands. + - `"computer_use_preview"` - - `action: object { commands, max_output_length, timeout_ms }` + - `"computer_use"` - The shell commands and limits that describe how to run the tool call. + - `"web_search_preview_2025_03_11"` - - `commands: array of string` + - `"image_generation"` - Ordered shell commands for the execution environment to run. + - `"code_interpreter"` - - `max_output_length: optional number` + - `BetaToolChoiceFunction object { name, type }` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + Use this option to force the model to call a specific function. - - `timeout_ms: optional number` + - `name: string` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + The name of the function to call. - - `call_id: string` + - `type: "function"` - The unique ID of the shell tool call generated by the model. + For function calling, the type is always `function`. - - `type: "shell_call"` + - `"function"` - The type of the item. Always `shell_call`. + - `BetaToolChoiceMcp object { server_label, type, name }` - - `"shell_call"` + Use this option to force the model to call a specific tool on a remote MCP server. - - `id: optional string` + - `server_label: string` - The unique ID of the shell tool call. Populated when this item is returned via API. + The label of the MCP server to use. - - `agent: optional object { agent_name }` + - `type: "mcp"` - The agent that produced this item. + For MCP tools, the type is always `mcp`. - - `agent_name: string` + - `"mcp"` - The canonical name of the agent that produced this item. + - `name: optional string` - - `caller: optional object { type } or object { caller_id, type }` + The name of the tool to call on the server. - The execution context that produced this tool call. + - `BetaToolChoiceCustom object { name, type }` - - `Direct object { type }` + Use this option to force the model to call a specific custom tool. - - `type: "direct"` + - `name: string` - The caller type. Always `direct`. + The name of the custom tool to call. - - `"direct"` + - `type: "custom"` - - `Program object { caller_id, type }` + For custom tool calling, the type is always `custom`. - - `caller_id: string` + - `"custom"` - The call ID of the program item that produced this tool call. + - `BetaSpecificProgrammaticToolCallingParam object { type }` - - `type: "program"` + - `type: "programmatic_tool_calling"` - The caller type. Always `program`. + The tool to call. Always `programmatic_tool_calling`. - - `"program"` + - `"programmatic_tool_calling"` - - `environment: optional BetaLocalEnvironment or BetaContainerReference` + - `BetaToolChoiceApplyPatch object { type }` - The environment to execute the shell commands in. + Forces the model to call the apply_patch tool when executing a tool call. - - `BetaLocalEnvironment object { type, skills }` + - `type: "apply_patch"` - - `BetaContainerReference object { container_id, type }` + The tool to call. Always `apply_patch`. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"apply_patch"` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `BetaToolChoiceShell object { type }` - - `"in_progress"` + Forces the model to call the shell tool when a tool call is required. - - `"completed"` + - `type: "shell"` - - `"incomplete"` + The tool to call. Always `shell`. - - `ShellCallOutput object { call_id, output, type, 5 more }` + - `"shell"` - The streamed output items emitted by a shell tool call. + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - - `call_id: string` + 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 unique ID of the shell tool call generated by the model. + We support the following categories of tools: - - `output: array of BetaResponseFunctionShellCallOutputContent` + - **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. - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `Function object { name, parameters, strict, 5 more }` - - `outcome: object { type } or object { exit_code, type }` + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - The exit or timeout outcome associated with this shell call. + - `name: string` - - `Timeout object { type }` + The name of the function to call. - Indicates that the shell call exceeded its configured time limit. + - `parameters: map[unknown]` - - `type: "timeout"` + A JSON schema object describing the parameters of the function. - The outcome type. Always `timeout`. + - `strict: boolean` - - `"timeout"` + Whether strict parameter validation is enforced for this function tool. - - `Exit object { exit_code, type }` + - `type: "function"` - Indicates that the shell commands finished and returned an exit code. + The type of the function tool. Always `function`. - - `exit_code: number` + - `"function"` - The exit code returned by the shell process. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "exit"` + The tool invocation context(s). - The outcome type. Always `exit`. + - `"direct"` - - `"exit"` + - `"programmatic"` - - `stderr: string` + - `defer_loading: optional boolean` - Captured stderr output for the shell call. + Whether this function is deferred and loaded via tool search. - - `stdout: string` + - `description: optional string` - Captured stdout output for the shell call. + A description of the function. Used by the model to determine whether or not to call the function. - - `type: "shell_call_output"` + - `output_schema: optional map[unknown]` - The type of the item. Always `shell_call_output`. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `"shell_call_output"` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `id: 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). - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `type: "file_search"` - - `agent: optional object { agent_name }` + The type of the file search tool. Always `file_search`. - The agent that produced this item. + - `"file_search"` - - `agent_name: string` + - `vector_store_ids: array of string` - The canonical name of the agent that produced this item. + The IDs of the vector stores to search. - - `caller: optional object { type } or object { caller_id, type }` + - `filters: optional object { key, type, value } or object { filters, type }` - The execution context that produced this tool call. + A filter to apply. - - `Direct object { type }` + - `ComparisonFilter object { key, type, value }` - - `type: "direct"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The caller type. Always `direct`. + - `key: string` - - `"direct"` + The key to compare against the value. - - `Program object { caller_id, type }` + - `type: "eq" or "ne" or "gt" or 5 more` - - `caller_id: string` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The call ID of the program item that produced this 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 - - `type: "program"` + - `"eq"` - The caller type. Always `program`. + - `"ne"` - - `"program"` + - `"gt"` - - `max_output_length: optional number` + - `"gte"` - The maximum number of UTF-8 characters captured for this shell call's combined output. + - `"lt"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"lte"` - The status of the shell call output. + - `"in"` - - `"in_progress"` + - `"nin"` - - `"completed"` + - `value: string or number or boolean or array of string or number` - - `"incomplete"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `ApplyPatchCall object { call_id, operation, status, 4 more }` + - `string` - A tool call representing a request to create, delete, or update files using diff patches. + - `number` - - `call_id: string` + - `boolean` - The unique ID of the apply patch tool call generated by the model. + - `array of string or number` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `string` - The specific create, delete, or update instruction for the apply_patch tool call. + - `number` - - `CreateFile object { diff, path, type }` + - `CompoundFilter object { filters, type }` - Instruction for creating a new file via the apply_patch tool. + Combine multiple filters using `and` or `or`. - - `diff: string` + - `filters: array of object { key, type, value } or unknown` - Unified diff content to apply when creating the file. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `path: string` + - `ComparisonFilter object { key, type, value }` - Path of the file to create relative to the workspace root. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `type: "create_file"` + - `key: string` - The operation type. Always `create_file`. + The key to compare against the value. - - `"create_file"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `DeleteFile object { path, type }` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - Instruction for deleting an existing file via the apply_patch tool. + - `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 - - `path: string` + - `"eq"` - Path of the file to delete relative to the workspace root. + - `"ne"` - - `type: "delete_file"` + - `"gt"` - The operation type. Always `delete_file`. + - `"gte"` - - `"delete_file"` + - `"lt"` - - `UpdateFile object { diff, path, type }` + - `"lte"` - Instruction for updating an existing file via the apply_patch tool. + - `"in"` - - `diff: string` + - `"nin"` - Unified diff content to apply to the existing file. + - `value: string or number or boolean or array of string or number` - - `path: string` + The value to compare against the attribute key; supports string, number, or boolean types. - Path of the file to update relative to the workspace root. + - `string` - - `type: "update_file"` + - `number` - The operation type. Always `update_file`. + - `boolean` - - `"update_file"` + - `array of string or number` - - `status: "in_progress" or "completed"` + - `string` - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `number` - - `"in_progress"` + - `unknown` - - `"completed"` + - `type: "and" or "or"` - - `type: "apply_patch_call"` + Type of operation: `and` or `or`. - The type of the item. Always `apply_patch_call`. + - `"and"` - - `"apply_patch_call"` + - `"or"` - - `id: optional string` + - `max_num_results: optional number` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `agent: optional object { agent_name }` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - The agent that produced this item. + Ranking options for search. - - `agent_name: string` + - `hybrid_search: optional object { embedding_weight, text_weight }` - The canonical name of the agent that produced this item. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `caller: optional object { type } or object { caller_id, type }` + - `embedding_weight: number` - The execution context that produced this tool call. + The weight of the embedding in the reciprocal ranking fusion. - - `Direct object { type }` + - `text_weight: number` - - `type: "direct"` + The weight of the text in the reciprocal ranking fusion. - The caller type. Always `direct`. + - `ranker: optional "auto" or "default-2024-11-15"` - - `"direct"` + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `Program object { caller_id, type }` + - `display_height: number` - - `caller_id: string` + The height of the computer display. - The call ID of the program item that produced this tool call. + - `display_width: number` - - `type: "program"` + The width of the computer display. - The caller type. Always `program`. + - `environment: "windows" or "mac" or "linux" or 2 more` - - `"program"` + The type of computer environment to control. - - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` + - `"windows"` - The streamed output emitted by an apply patch tool call. + - `"mac"` - - `call_id: string` + - `"linux"` - The unique ID of the apply patch tool call generated by the model. + - `"ubuntu"` - - `status: "completed" or "failed"` + - `"browser"` - The status of the apply patch tool call output. One of `completed` or `failed`. + - `type: "computer_use_preview"` - - `"completed"` + The type of the computer use tool. Always `computer_use_preview`. - - `"failed"` + - `"computer_use_preview"` - - `type: "apply_patch_call_output"` + - `WebSearch object { type, filters, search_context_size, user_location }` - The type of the item. Always `apply_patch_call_output`. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `"apply_patch_call_output"` + - `type: "web_search" or "web_search_2025_08_26"` - - `id: optional string` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `"web_search"` - - `agent: optional object { agent_name }` + - `"web_search_2025_08_26"` - The agent that produced this item. + - `filters: optional object { allowed_domains }` - - `agent_name: string` + Filters for the search. - The canonical name of the agent that produced this item. + - `allowed_domains: optional array of string` - - `caller: optional object { type } or object { caller_id, type }` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - The execution context that produced this tool call. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `Direct object { type }` + - `search_context_size: optional "low" or "medium" or "high"` - - `type: "direct"` + 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 caller type. Always `direct`. + - `"low"` - - `"direct"` + - `"medium"` - - `Program object { caller_id, type }` + - `"high"` - - `caller_id: string` + - `user_location: optional object { city, country, region, 2 more }` - The call ID of the program item that produced this tool call. + The approximate location of the user. - - `type: "program"` + - `city: optional string` - The caller type. Always `program`. + Free text input for the city of the user, e.g. `San Francisco`. - - `"program"` + - `country: optional string` - - `output: optional string` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `region: optional string` - - `McpListTools object { id, server_label, tools, 3 more }` + Free text input for the region of the user, e.g. `California`. - A list of tools available on an MCP server. + - `timezone: optional string` - - `id: string` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The unique ID of the list. + - `type: optional "approximate"` - - `server_label: string` + The type of location approximation. Always `approximate`. - The label of the MCP server. + - `"approximate"` - - `tools: array of object { input_schema, name, annotations, description }` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - The tools available on the server. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `input_schema: unknown` + - `server_label: string` - The JSON schema describing the tool's input. + A label for this MCP server, used to identify it in tool calls. - - `name: string` + - `type: "mcp"` - The name of the tool. + The type of the MCP tool. Always `mcp`. - - `annotations: optional unknown` + - `"mcp"` - Additional annotations about the tool. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `description: optional string` + The tool invocation context(s). - The description of the tool. + - `"direct"` - - `type: "mcp_list_tools"` + - `"programmatic"` - The type of the item. Always `mcp_list_tools`. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `"mcp_list_tools"` + List of allowed tool names or a filter object. - - `agent: optional object { agent_name }` + - `McpAllowedTools = array of string` - The agent that produced this item. + A string array of allowed tool names - - `agent_name: string` + - `McpToolFilter object { read_only, tool_names }` - The canonical name of the agent that produced this item. + A filter object to specify which tools are allowed. - - `error: optional string` + - `read_only: optional boolean` - Error message if the server could not list tools. + 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. - - `McpApprovalRequest object { id, arguments, name, 3 more }` + - `tool_names: optional array of string` - A request for human approval of a tool invocation. + List of allowed tool names. - - `id: string` + - `authorization: optional string` - The unique ID of the approval request. + 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. - - `arguments: string` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - A JSON string of arguments for the tool. + 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). - - `name: string` + Currently supported `connector_id` values are: - The name of the tool to run. + - 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` - - `server_label: string` + - `"connector_dropbox"` - The label of the MCP server making the request. + - `"connector_gmail"` - - `type: "mcp_approval_request"` + - `"connector_googlecalendar"` - The type of the item. Always `mcp_approval_request`. + - `"connector_googledrive"` - - `"mcp_approval_request"` + - `"connector_microsoftteams"` - - `agent: optional object { agent_name }` + - `"connector_outlookcalendar"` - The agent that produced this item. + - `"connector_outlookemail"` - - `agent_name: string` + - `"connector_sharepoint"` - The canonical name of the agent that produced this item. + - `defer_loading: optional boolean` - - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` + Whether this MCP tool is deferred and discovered via tool search. - A response to an MCP approval request. + - `headers: optional map[string]` - - `approval_request_id: string` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The ID of the approval request being answered. + - `require_approval: optional object { always, never } or "always" or "never"` - - `approve: boolean` + Specify which of the MCP server's tools require approval. - Whether the request was approved. + - `McpToolApprovalFilter object { always, never }` - - `type: "mcp_approval_response"` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - The type of the item. Always `mcp_approval_response`. + - `always: optional object { read_only, tool_names }` - - `"mcp_approval_response"` + A filter object to specify which tools are allowed. - - `id: optional string` + - `read_only: optional boolean` - The unique ID of the approval 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. - - `agent: optional object { agent_name }` + - `tool_names: optional array of string` - The agent that produced this item. + List of allowed tool names. - - `agent_name: string` + - `never: optional object { read_only, tool_names }` - The canonical name of the agent that produced this item. + A filter object to specify which tools are allowed. - - `reason: optional string` + - `read_only: optional boolean` - Optional reason for the decision. + 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. - - `McpCall object { id, arguments, name, 7 more }` + - `tool_names: optional array of string` - An invocation of a tool on an MCP server. + List of allowed tool names. - - `id: string` + - `McpToolApprovalSetting = "always" or "never"` - The unique ID of the tool call. + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `arguments: string` + - `"always"` - A JSON string of the arguments passed to the tool. + - `"never"` - - `name: string` + - `server_description: optional string` - The name of the tool that was run. + Optional description of the MCP server, used to provide more context. - - `server_label: string` + - `server_url: optional string` - The label of the MCP server running the tool. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `type: "mcp_call"` + - `tunnel_id: optional string` - The type of the item. Always `mcp_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. - - `"mcp_call"` + - `CodeInterpreter object { container, type, allowed_callers }` - - `agent: optional object { agent_name }` + A tool that runs Python code to help generate a response to a prompt. - The agent that produced this item. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `agent_name: string` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - The canonical name of the agent that produced this item. + - `string` - - `approval_request_id: optional string` + The container ID. - 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. + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `error: optional string` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The error from the tool call, if any. + - `type: "auto"` - - `output: optional string` + Always `auto`. - The output from the tool call. + - `"auto"` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `file_ids: optional array of string` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + An optional list of uploaded files to make available to your code. - - `"in_progress"` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `"completed"` + The memory limit for the code interpreter container. - - `"incomplete"` + - `"1g"` - - `"calling"` + - `"4g"` - - `"failed"` + - `"16g"` - - `CustomToolCallOutput object { call_id, output, type, 3 more }` + - `"64g"` - The output of a custom tool call from your code, being sent back to the model. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `call_id: string` + Network access policy for the container. - The call ID, used to map this custom tool call output to a custom tool call. + - `BetaContainerNetworkPolicyDisabled object { type }` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `type: "code_interpreter"` - - `StringOutput = string` + The type of the code interpreter tool. Always `code_interpreter`. - A string of the output of the custom tool call. + - `"code_interpreter"` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `allowed_callers: optional array of "direct" or "programmatic"` - Text, image, or file output of the custom tool call. + The tool invocation context(s). - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `"direct"` - A text input to the model. + - `"programmatic"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `ProgrammaticToolCalling object { type }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `type: "programmatic_tool_calling"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + The type of the tool. Always `programmatic_tool_calling`. - A file input to the model. + - `"programmatic_tool_calling"` - - `type: "custom_tool_call_output"` + - `ImageGeneration object { type, action, background, 9 more }` - The type of the custom tool call output. Always `custom_tool_call_output`. + A tool that generates images using the GPT image models. - - `"custom_tool_call_output"` + - `type: "image_generation"` - - `id: optional string` + The type of the image generation tool. Always `image_generation`. - The unique ID of the custom tool call output in the OpenAI platform. + - `"image_generation"` - - `agent: optional object { agent_name }` + - `action: optional "generate" or "edit" or "auto"` - The agent that produced this item. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `agent_name: string` + - `"generate"` - The canonical name of the agent that produced this item. + - `"edit"` - - `caller: optional object { type } or object { caller_id, type }` + - `"auto"` - The execution context that produced this tool call. + - `background: optional "transparent" or "opaque" or "auto"` - - `Direct object { type }` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `type: "direct"` + - `"transparent"` - The caller type. Always `direct`. + - `"opaque"` - - `"direct"` + - `"auto"` - - `Program object { caller_id, type }` + - `input_fidelity: optional "high" or "low"` - - `caller_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 call ID of the program item that produced this tool call. + - `"high"` - - `type: "program"` + - `"low"` - The caller type. 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). - - `CustomToolCall object { call_id, input, name, 5 more }` + - `file_id: optional string` - A call to a custom tool created by the model. + File ID for the mask image. - - `call_id: string` + - `image_url: optional string` - An identifier used to map this custom tool call to a tool call output. + Base64-encoded mask image. - - `input: string` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The input for the custom tool call generated by the model. + The image generation model to use. Default: `gpt-image-1`. - - `name: string` + - `string` - The name of the custom tool being called. + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `type: "custom_tool_call"` + The image generation model to use. Default: `gpt-image-1`. - The type of the custom tool call. Always `custom_tool_call`. + - `"gpt-image-1"` - - `"custom_tool_call"` + - `"gpt-image-1-mini"` - - `id: optional string` + - `"gpt-image-1.5"` - The unique ID of the custom tool call in the OpenAI platform. + - `moderation: optional "auto" or "low"` - - `agent: optional object { agent_name }` + Moderation level for the generated image. Default: `auto`. - The agent that produced this item. + - `"auto"` - - `agent_name: string` + - `"low"` - The canonical name of the agent that produced this item. + - `output_compression: optional number` - - `caller: optional object { type } or object { caller_id, type }` + Compression level for the output image. Default: 100. - The execution context that produced this tool call. + - `output_format: optional "png" or "webp" or "jpeg"` - - `Direct object { type }` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `type: "direct"` + - `"png"` - - `"direct"` + - `"webp"` - - `Program object { caller_id, type }` + - `"jpeg"` - - `caller_id: string` + - `partial_images: optional number` - The call ID of the program item that produced this tool call. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `type: "program"` + - `quality: optional "low" or "medium" or "high" or "auto"` - - `"program"` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `namespace: optional string` + - `"low"` - The namespace of the custom tool being called. + - `"medium"` - - `CompactionTrigger object { type, agent }` + - `"high"` - Compacts the current context. Must be the final input item. + - `"auto"` - - `type: "compaction_trigger"` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - The type of the item. Always `compaction_trigger`. + 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`. - - `"compaction_trigger"` + - `string` - - `agent: optional object { agent_name }` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - The agent that produced this item. + 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`. - - `agent_name: string` + - `"1024x1024"` - The canonical name of the agent that produced this item. + - `"1024x1536"` - - `ItemReference object { id, agent, type }` + - `"1536x1024"` - An internal identifier for an item to reference. + - `"auto"` - - `id: string` + - `LocalShell object { type }` - The ID of the item to reference. + A tool that allows the model to execute shell commands in a local environment. - - `agent: optional object { agent_name }` + - `type: "local_shell"` - The agent that produced this item. + The type of the local shell tool. Always `local_shell`. - - `agent_name: string` + - `"local_shell"` - The canonical name of the agent that produced this item. + - `Shell object { type, allowed_callers, environment }` - - `type: optional "item_reference"` + A tool that allows the model to execute shell commands. - The type of item to reference. Always `item_reference`. + - `type: "shell"` - - `"item_reference"` + The type of the shell tool. Always `shell`. - - `Program object { id, call_id, code, 3 more }` + - `"shell"` - - `id: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The unique ID of this program item. + The tool invocation context(s). - - `call_id: string` + - `"direct"` - The stable call ID of the program item. + - `"programmatic"` - - `code: string` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - The JavaScript source executed by programmatic tool calling. + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `fingerprint: string` + - `BetaLocalEnvironment object { type, skills }` - Opaque program replay fingerprint that must be round-tripped. + - `BetaContainerReference object { container_id, type }` - - `type: "program"` + - `Custom object { name, type, allowed_callers, 3 more }` - The item type. Always `program`. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `"program"` + - `name: string` - - `agent: optional object { agent_name }` + The name of the custom tool, used to identify it in tool calls. - The agent that produced this item. + - `type: "custom"` - - `agent_name: string` + The type of the custom tool. Always `custom`. - The canonical name of the agent that produced this item. + - `"custom"` - - `ProgramOutput object { id, call_id, result, 3 more }` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `id: string` + The tool invocation context(s). - The unique ID of this program output item. + - `"direct"` - - `call_id: string` + - `"programmatic"` - The call ID of the program item. + - `defer_loading: optional boolean` - - `result: string` + Whether this tool should be deferred and discovered via tool search. - The result produced by the program item. + - `description: optional string` - - `status: "completed" or "incomplete"` + Optional description of the custom tool, used to provide more context. - The terminal status of the program output. + - `format: optional object { type } or object { definition, syntax, type }` - - `"completed"` + The input format for the custom tool. Default is unconstrained text. - - `"incomplete"` + - `Text object { type }` - - `type: "program_output"` + Unconstrained free-form text. - The item type. Always `program_output`. + - `type: "text"` - - `"program_output"` + Unconstrained text format. Always `text`. - - `agent: optional object { agent_name }` + - `"text"` - The agent that produced this item. + - `Grammar object { definition, syntax, type }` - - `agent_name: string` + A grammar defined by the user. - The canonical name of the agent that produced this item. + - `definition: string` - - `response_id: string` + The grammar definition. - The ID of the response that rejected the input. + - `syntax: "lark" or "regex"` - - `sequence_number: number` + The syntax of the grammar definition. One of `lark` or `regex`. - The sequence number for this event. + - `"lark"` - - `type: "response.inject.failed"` + - `"regex"` - The event discriminator. Always `response.inject.failed`. + - `type: "grammar"` - - `"response.inject.failed"` + Grammar format. Always `grammar`. - - `stream_id: optional string` + - `"grammar"` - The multiplexed WebSocket stream that emitted the event. This field is - present only when WebSocket multiplexing is enabled separately. + - `Namespace object { description, name, tools, type }` -### Beta Response Input Audio + Groups function/custom tools under a shared namespace. -- `BetaResponseInputAudio object { input_audio, type }` + - `description: string` - An audio input to the model. + A description of the namespace shown to the model. - - `input_audio: object { data, format }` + - `name: string` - - `data: string` + The namespace name used in tool calls (for example, `crm`). - Base64-encoded audio data. + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `format: "mp3" or "wav"` + The function/custom tools available inside this namespace. - The format of the audio data. Currently supported formats are `mp3` and - `wav`. + - `Function object { name, type, allowed_callers, 5 more }` - - `"mp3"` + - `name: string` - - `"wav"` + - `type: "function"` - - `type: "input_audio"` + - `"function"` - The type of the input item. Always `input_audio`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"input_audio"` + The tool invocation context(s). -### Beta Response Input Content + - `"direct"` -- `BetaResponseInputContent = BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `"programmatic"` - A text input to the model. + - `defer_loading: optional boolean` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + Whether this function should be deferred and discovered via tool search. - A text input to the model. + - `description: optional string` - - `text: string` + - `output_schema: optional map[unknown]` - The text input to the model. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `type: "input_text"` + - `parameters: optional unknown` - The type of the input item. Always `input_text`. + - `strict: optional boolean` - - `"input_text"` + 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. - - `prompt_cache_breakpoint: optional object { mode }` + - `Custom object { name, type, allowed_callers, 3 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. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `mode: "explicit"` + - `name: string` - The breakpoint mode. Always `explicit`. + The name of the custom tool, used to identify it in tool calls. - - `"explicit"` + - `type: "custom"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + The type of the custom tool. Always `custom`. - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `"custom"` - - `detail: "low" or "high" or "auto" or "original"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The tool invocation context(s). - - `"low"` + - `"direct"` - - `"high"` + - `"programmatic"` - - `"auto"` + - `defer_loading: optional boolean` - - `"original"` + Whether this tool should be deferred and discovered via tool search. - - `type: "input_image"` + - `description: optional string` - The type of the input item. Always `input_image`. + Optional description of the custom tool, used to provide more context. - - `"input_image"` + - `format: optional object { type } or object { definition, syntax, type }` - - `file_id: optional string` + The input format for the custom tool. Default is unconstrained text. - The ID of the file to be sent to the model. + - `Text object { type }` - - `image_url: optional string` + Unconstrained free-form text. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `type: "text"` - - `prompt_cache_breakpoint: optional object { mode }` + Unconstrained text format. Always `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. + - `"text"` - - `mode: "explicit"` + - `Grammar object { definition, syntax, type }` - The breakpoint mode. Always `explicit`. + A grammar defined by the user. - - `"explicit"` + - `definition: string` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + The grammar definition. - A file input to the model. + - `syntax: "lark" or "regex"` - - `type: "input_file"` + The syntax of the grammar definition. One of `lark` or `regex`. - The type of the input item. Always `input_file`. + - `"lark"` - - `"input_file"` + - `"regex"` - - `detail: optional "auto" or "low" or "high"` + - `type: "grammar"` - 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`. + Grammar format. Always `grammar`. - - `"auto"` + - `"grammar"` - - `"low"` + - `type: "namespace"` - - `"high"` + The type of the tool. Always `namespace`. - - `file_data: optional string` + - `"namespace"` - The content of the file to be sent to the model. + - `ToolSearch object { type, description, execution, parameters }` - - `file_id: optional string` + Hosted or BYOT tool search configuration for deferred tools. - The ID of the file to be sent to the model. + - `type: "tool_search"` - - `file_url: optional string` + The type of the tool. Always `tool_search`. - The URL of the file to be sent to the model. + - `"tool_search"` - - `filename: optional string` + - `description: optional string` - The name of the file to be sent to the model. + Description shown to the model for a client-executed tool search tool. - - `prompt_cache_breakpoint: optional object { mode }` + - `execution: optional "server" or "client"` - 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 tool search is executed by the server or by the client. - - `mode: "explicit"` + - `"server"` - The breakpoint mode. Always `explicit`. + - `"client"` - - `"explicit"` + - `parameters: optional unknown` -### Beta Response Input File + Parameter schema for a client-executed tool search tool. -- `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - A file input 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). - - `type: "input_file"` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - The type of the input item. Always `input_file`. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `"input_file"` + - `"web_search_preview"` - - `detail: optional "auto" or "low" or "high"` + - `"web_search_preview_2025_03_11"` - 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_content_types: optional array of "text" or "image"` - - `"auto"` + - `"text"` - - `"low"` + - `"image"` - - `"high"` + - `search_context_size: optional "low" or "medium" or "high"` - - `file_data: optional string` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - The content of the file to be sent to the model. + - `"low"` - - `file_id: optional string` + - `"medium"` - The ID of the file to be sent to the model. + - `"high"` - - `file_url: optional string` + - `user_location: optional object { type, city, country, 2 more }` - The URL of the file to be sent to the model. + The user's location. - - `filename: optional string` + - `type: "approximate"` - The name of the file to be sent to the model. + The type of location approximation. Always `approximate`. - - `prompt_cache_breakpoint: optional object { mode }` + - `"approximate"` - 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. + - `city: optional string` - - `mode: "explicit"` + Free text input for the city of the user, e.g. `San Francisco`. - The breakpoint mode. Always `explicit`. + - `country: optional string` - - `"explicit"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. -### Beta Response Input File Content + - `region: optional string` -- `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` + Free text input for the region of the user, e.g. `California`. - A file input to the model. + - `timezone: optional string` - - `type: "input_file"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The type of the input item. Always `input_file`. + - `ApplyPatch object { type, allowed_callers }` - - `"input_file"` + Allows the assistant to create, delete, or update files using unified diffs. - - `detail: optional "auto" or "low" or "high"` + - `type: "apply_patch"` - 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 tool. Always `apply_patch`. - - `"auto"` + - `"apply_patch"` - - `"low"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"high"` + The tool invocation context(s). - - `file_data: optional string` + - `"direct"` - The base64-encoded data of the file to be sent to the model. + - `"programmatic"` - - `file_id: optional string` + - `top_p: number` - The ID of the file to be sent to the model. + 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. - - `file_url: optional string` + We generally recommend altering this or `temperature` but not both. - The URL of the file to be sent to the model. + - `background: optional boolean` - - `filename: optional string` + Whether to run the model response in the background. + [Learn more](/docs/guides/background). - The name of the file to be sent to the model. + - `completed_at: optional number` - - `prompt_cache_breakpoint: optional object { mode }` + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - 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. + - `conversation: optional object { id }` - - `mode: "explicit"` + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - The breakpoint mode. Always `explicit`. + - `id: string` - - `"explicit"` + The unique ID of the conversation that this response was associated with. -### Beta Response Input Image + - `max_output_tokens: optional number` -- `BetaResponseInputImage object { detail, type, file_id, 2 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). - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `max_tool_calls: optional number` - - `detail: "low" or "high" or "auto" or "original"` + 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 detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `moderation: optional object { input, output }` - - `"low"` + Moderation results for the response input and output, if moderated completions were requested. - - `"high"` + - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - - `"auto"` + Moderation for the response input. - - `"original"` + - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` - - `type: "input_image"` + A moderation result produced for the response input or output. - The type of the input item. Always `input_image`. + - `categories: map[boolean]` - - `"input_image"` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `file_id: optional string` + - `category_applied_input_types: map[array of "text" or "image"]` - The ID of the file to be sent to the model. + Which modalities of input are reflected by the score for each category. - - `image_url: optional string` + - `"text"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `"image"` - - `prompt_cache_breakpoint: optional object { mode }` + - `category_scores: map[number]` - 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 dictionary of moderation categories to scores. - - `mode: "explicit"` + - `flagged: boolean` - The breakpoint mode. Always `explicit`. + A boolean indicating whether the content was flagged by any category. - - `"explicit"` + - `model: string` -### Beta Response Input Image Content + The moderation model that produced this result. -- `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + - `type: "moderation_result"` - An image input to the model. Learn about [image inputs](/docs/guides/vision) + The object type, which was always `moderation_result` for successful moderation results. - - `type: "input_image"` + - `"moderation_result"` - The type of the input item. Always `input_image`. + - `Error object { code, message, type }` - - `"input_image"` + An error produced while attempting moderation for the response input or output. - - `detail: optional "low" or "high" or "auto" or "original"` + - `code: string` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The error code. - - `"low"` + - `message: string` - - `"high"` + The error message. - - `"auto"` + - `type: "error"` - - `"original"` + The object type, which was always `error` for moderation failures. - - `file_id: optional string` + - `"error"` - The ID of the file to be sent to the model. + - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - - `image_url: optional string` + Moderation for the response output. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` - - `prompt_cache_breakpoint: optional object { mode }` + A moderation result produced for the response input or 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. + - `categories: map[boolean]` - - `mode: "explicit"` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - The breakpoint mode. Always `explicit`. + - `category_applied_input_types: map[array of "text" or "image"]` - - `"explicit"` + Which modalities of input are reflected by the score for each category. -### Beta Response Input Message Content List + - `"text"` -- `BetaResponseInputMessageContentList = array of BetaResponseInputContent` + - `"image"` - A list of one or many input items to the model, containing different content - types. + - `category_scores: map[number]` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + A dictionary of moderation categories to scores. - A text input to the model. + - `flagged: boolean` - - `text: string` + A boolean indicating whether the content was flagged by any category. - The text input to the model. + - `model: string` - - `type: "input_text"` + The moderation model that produced this result. - The type of the input item. Always `input_text`. + - `type: "moderation_result"` - - `"input_text"` + The object type, which was always `moderation_result` for successful moderation results. - - `prompt_cache_breakpoint: optional object { mode }` + - `"moderation_result"` - 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 object { code, message, type }` - - `mode: "explicit"` + An error produced while attempting moderation for the response input or output. - The breakpoint mode. Always `explicit`. + - `code: string` - - `"explicit"` + The error code. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `message: string` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + The error message. - - `detail: "low" or "high" or "auto" or "original"` + - `type: "error"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The object type, which was always `error` for moderation failures. - - `"low"` + - `"error"` - - `"high"` + - `output_text: optional string` - - `"auto"` + 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. - - `"original"` + - `previous_response_id: optional string` - - `type: "input_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 input item. Always `input_image`. + - `prompt: optional BetaResponsePrompt` - - `"input_image"` + Reference to a prompt template and its variables. + [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). - - `file_id: optional string` + - `id: string` - The ID of the file to be sent to the model. + The unique identifier of the prompt template to use. - - `image_url: optional string` + - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + 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. - - `prompt_cache_breakpoint: optional object { mode }` + - `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. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `mode: "explicit"` + A text input to the model. - The breakpoint mode. Always `explicit`. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `"explicit"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - `BetaResponseInputFile object { type, detail, file_data, 4 more }` A file input to the model. - - `type: "input_file"` + - `version: optional string` - The type of the input item. Always `input_file`. + Optional version of the prompt template. - - `"input_file"` + - `prompt_cache_key: optional string` - - `detail: optional "auto" or "low" or "high"` + 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 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`. + - `prompt_cache_options: optional object { mode, ttl }` - - `"auto"` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `"low"` + - `mode: "implicit" or "explicit"` - - `"high"` + Whether implicit prompt-cache breakpoints were enabled. - - `file_data: optional string` + - `"implicit"` - The content of the file to be sent to the model. + - `"explicit"` - - `file_id: optional string` + - `ttl: "30m"` - The ID of the file to be sent to the model. + The minimum lifetime applied to each cache breakpoint. - - `file_url: optional string` + - `"30m"` - The URL of the file to be sent to the model. + - `prompt_cache_retention: optional "in_memory" or "24h"` - - `filename: optional string` + Deprecated. Use `prompt_cache_options.ttl` instead. - The name of the file to be sent to the model. + 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. - - `prompt_cache_breakpoint: optional object { mode }` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - 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. + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `mode: "explicit"` + - `"in_memory"` - The breakpoint mode. Always `explicit`. + - `"24h"` - - `"explicit"` + - `reasoning: optional object { context, effort, generate_summary, 2 more }` -### Beta Response Input Message Item + **gpt-5 and o-series models only** -- `BetaResponseInputMessageItem object { id, content, role, 3 more }` + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `id: string` + - `context: optional "auto" or "current_turn" or "all_turns"` - The unique ID of the message input. + 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`. - - `content: BetaResponseInputMessageContentList` + When returned on a response, this is the effective reasoning context mode + used for the response. - A list of one or many input items to the model, containing different content - types. + - `"auto"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `"current_turn"` - A text input to the model. + - `"all_turns"` + + - `effort: optional "none" or "minimal" or "low" or 4 more` + + 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. - - `text: string` + - `"none"` - The text input to the model. + - `"minimal"` - - `type: "input_text"` + - `"low"` - The type of the input item. Always `input_text`. + - `"medium"` - - `"input_text"` + - `"high"` - - `prompt_cache_breakpoint: optional object { mode }` + - `"xhigh"` - 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. + - `"max"` - - `mode: "explicit"` + - `generate_summary: optional "auto" or "concise" or "detailed"` - The breakpoint mode. Always `explicit`. + **Deprecated:** use `summary` instead. - - `"explicit"` + 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`. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `"auto"` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `"concise"` - - `detail: "low" or "high" or "auto" or "original"` + - `"detailed"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `mode: optional string or "standard" or "pro"` - - `"low"` + Controls the reasoning execution mode for the request. - - `"high"` + When returned on a response, this is the effective execution mode. - - `"auto"` + - `string` - - `"original"` + - `"standard" or "pro"` - - `type: "input_image"` + Controls the reasoning execution mode for the request. - The type of the input item. Always `input_image`. + When returned on a response, this is the effective execution mode. - - `"input_image"` + - `"standard"` - - `file_id: optional string` + - `"pro"` - The ID of the file to be sent to the model. + - `summary: optional "auto" or "concise" or "detailed"` - - `image_url: optional 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 URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `prompt_cache_breakpoint: optional object { mode }` + - `"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. + - `"concise"` - - `mode: "explicit"` + - `"detailed"` - The breakpoint mode. Always `explicit`. + - `safety_identifier: optional string` - - `"explicit"` + 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). - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `service_tier: optional "auto" or "default" or "flex" or 2 more` - A file input to the model. + Specifies the processing type used for serving the request. - - `type: "input_file"` + - 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 type of the input item. Always `input_file`. + 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. - - `"input_file"` + - `"auto"` - - `detail: optional "auto" or "low" or "high"` + - `"default"` - 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`. + - `"flex"` - - `"auto"` + - `"scale"` - - `"low"` + - `"priority"` - - `"high"` + - `status: optional BetaResponseStatus` - - `file_data: optional string` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - The content of the file to be sent to the model. + - `"completed"` - - `file_id: optional string` + - `"failed"` - The ID of the file to be sent to the model. + - `"in_progress"` - - `file_url: optional string` + - `"cancelled"` - The URL of the file to be sent to the model. + - `"queued"` - - `filename: optional string` + - `"incomplete"` - The name of the file to be sent to the model. + - `text: optional BetaResponseTextConfig` - - `prompt_cache_breakpoint: optional object { mode }` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn 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. + - [Text inputs and outputs](/docs/guides/text) + - [Structured Outputs](/docs/guides/structured-outputs) - - `mode: "explicit"` + - `format: optional BetaResponseFormatTextConfig` - The breakpoint mode. Always `explicit`. + An object specifying the format that the model must output. - - `"explicit"` + 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). - - `role: "user" or "system" or "developer"` + The default format is `{ "type": "text" }` with no additional options. - The role of the message input. One of `user`, `system`, or `developer`. + **Not recommended for gpt-4o and newer models:** - - `"user"` + 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. - - `"system"` + - `Text object { type }` - - `"developer"` + Default response format. Used to generate text responses. - - `type: "message"` + - `type: "text"` - The type of the message input. Always set to `message`. + The type of response format being defined. Always `text`. - - `"message"` + - `"text"` - - `agent: optional object { agent_name }` + - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` - The agent that produced this item. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `agent_name: string` + - `name: string` - The canonical name of the agent that produced this item. + 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. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `schema: map[unknown]` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `"in_progress"` + - `type: "json_schema"` - - `"completed"` + The type of response format being defined. Always `json_schema`. - - `"incomplete"` + - `"json_schema"` -### Beta Response Input Text + - `description: optional string` -- `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + A description of what the response format is for, used by the model to + determine how to respond in the format. - A text input to the model. + - `strict: optional boolean` - - `text: 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 text input to the model. + - `JSONObject object { type }` - - `type: "input_text"` + 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 input item. Always `input_text`. + - `type: "json_object"` - - `"input_text"` + The type of response format being defined. Always `json_object`. - - `prompt_cache_breakpoint: optional object { mode }` + - `"json_object"` - 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. + - `verbosity: optional "low" or "medium" or "high"` - - `mode: "explicit"` + 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 breakpoint mode. Always `explicit`. + - `"low"` - - `"explicit"` + - `"medium"` -### Beta Response Input Text Content + - `"high"` -- `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + - `top_logprobs: optional number` - A text input to the model. + 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. - - `text: string` + - `truncation: optional "auto" or "disabled"` - The text input to the model. + The truncation strategy to use for the model response. - - `type: "input_text"` + - `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 type of the input item. Always `input_text`. + - `"auto"` - - `"input_text"` + - `"disabled"` - - `prompt_cache_breakpoint: optional object { mode }` + - `usage: optional BetaResponseUsage` - 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. + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `mode: "explicit"` + - `input_tokens: number` - The breakpoint mode. Always `explicit`. + The number of input tokens. - - `"explicit"` + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` -### Beta Response Local Environment + A detailed breakdown of the input tokens. -- `BetaResponseLocalEnvironment object { type }` + - `cache_write_tokens: number` - Represents the use of a local environment to perform shell actions. + The number of input tokens that were written to the cache. - - `type: "local"` + - `cached_tokens: number` - The environment type. Always `local`. + The number of tokens that were retrieved from the cache. + [More on prompt caching](/docs/guides/prompt-caching). - - `"local"` + - `output_tokens: number` -### Beta Response Mcp Call Arguments Delta Event + The number of output tokens. -- `BetaResponseMcpCallArgumentsDeltaEvent object { delta, item_id, output_index, 3 more }` + - `output_tokens_details: object { reasoning_tokens }` - Emitted when there is a delta (partial update) to the arguments of an MCP tool call. + A detailed breakdown of the output tokens. - - `delta: string` + - `reasoning_tokens: number` - A JSON string containing the partial update to the arguments for the MCP tool call. + The number of reasoning tokens. - - `item_id: string` + - `total_tokens: number` - The unique identifier of the MCP tool call item being processed. + The total number of tokens used. - - `output_index: number` + - `user: optional string` - The index of the output item in the response's output array. + 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). - `sequence_number: number` The sequence number of this event. - - `type: "response.mcp_call_arguments.delta"` + - `type: "response.incomplete"` - The type of the event. Always 'response.mcp_call_arguments.delta'. + The type of the event. Always `response.incomplete`. - - `"response.mcp_call_arguments.delta"` + - `"response.incomplete"` - `agent: optional object { agent_name }` @@ -132640,259 +130610,250 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. -### Beta Response Mcp Call Arguments Done Event - -- `BetaResponseMcpCallArgumentsDoneEvent object { arguments, item_id, output_index, 3 more }` - - Emitted when the arguments for an MCP tool call are finalized. - - - `arguments: string` - - A JSON string containing the finalized arguments for the MCP tool call. +### Beta Response Inject Created Event - - `item_id: string` +- `BetaResponseInjectCreatedEvent object { response_id, sequence_number, type, stream_id }` - The unique identifier of the MCP tool call item being processed. + Emitted when all injected input items were validated and committed to the + active response. - - `output_index: number` + - `response_id: string` - The index of the output item in the response's output array. + The ID of the response that accepted the input. - `sequence_number: number` - The sequence number of this event. - - - `type: "response.mcp_call_arguments.done"` - - The type of the event. Always 'response.mcp_call_arguments.done'. - - - `"response.mcp_call_arguments.done"` - - - `agent: optional object { agent_name }` + The sequence number for this event. - The agent that owns this multi-agent streaming event. + - `type: "response.inject.created"` - - `agent_name: string` + The event discriminator. Always `response.inject.created`. - The canonical name of the agent that produced this item. + - `"response.inject.created"` -### Beta Response Mcp Call Completed Event + - `stream_id: optional string` -- `BetaResponseMcpCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` + The multiplexed WebSocket stream that emitted the event. This field is + present only when WebSocket multiplexing is enabled separately. - Emitted when an MCP tool call has completed successfully. +### Beta Response Inject Event - - `item_id: string` +- `BetaResponseInjectEvent object { input, response_id, type }` - The ID of the MCP tool call item that completed. + Injects input items into an active response over a WebSocket connection. + The items are validated and committed atomically. Currently, the server + accepts client-owned tool outputs that resume a waiting agent. - - `output_index: number` + - `input: array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - The index of the output item that completed. + Input items to inject into the active response. - - `sequence_number: number` + - `BetaEasyInputMessage object { content, role, phase, type }` - The sequence number of this event. + 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: "response.mcp_call.completed"` + - `content: string or BetaResponseInputMessageContentList` - The type of the event. Always 'response.mcp_call.completed'. + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `"response.mcp_call.completed"` + - `TextInput = string` - - `agent: optional object { agent_name }` + A text input to the model. - The agent that owns this multi-agent streaming event. + - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` - - `agent_name: string` + A list of one or many input items to the model, containing different content + types. - The canonical name of the agent that produced this item. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` -### Beta Response Mcp Call Failed Event + A text input to the model. -- `BetaResponseMcpCallFailedEvent object { item_id, output_index, sequence_number, 2 more }` + - `text: string` - Emitted when an MCP tool call has failed. + The text input to the model. - - `item_id: string` + - `type: "input_text"` - The ID of the MCP tool call item that failed. + The type of the input item. Always `input_text`. - - `output_index: number` + - `"input_text"` - The index of the output item that failed. + - `prompt_cache_breakpoint: optional object { mode }` - - `sequence_number: number` + 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 sequence number of this event. + - `mode: "explicit"` - - `type: "response.mcp_call.failed"` + The breakpoint mode. Always `explicit`. - The type of the event. Always 'response.mcp_call.failed'. + - `"explicit"` - - `"response.mcp_call.failed"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `agent: optional object { agent_name }` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - The agent that owns this multi-agent streaming event. + - `detail: "low" or "high" or "auto" or "original"` - - `agent_name: string` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The canonical name of the agent that produced this item. + - `"low"` -### Beta Response Mcp Call In Progress Event + - `"high"` -- `BetaResponseMcpCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + - `"auto"` - Emitted when an MCP tool call is in progress. + - `"original"` - - `item_id: string` + - `type: "input_image"` - The unique identifier of the MCP tool call item being processed. + The type of the input item. Always `input_image`. - - `output_index: number` + - `"input_image"` - The index of the output item in the response's output array. + - `file_id: optional string` - - `sequence_number: number` + The ID of the file to be sent to the model. - The sequence number of this event. + - `image_url: optional string` - - `type: "response.mcp_call.in_progress"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The type of the event. Always 'response.mcp_call.in_progress'. + - `prompt_cache_breakpoint: optional object { mode }` - - `"response.mcp_call.in_progress"` + 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. - - `agent: optional object { agent_name }` + - `mode: "explicit"` - The agent that owns this multi-agent streaming event. + The breakpoint mode. Always `explicit`. - - `agent_name: string` + - `"explicit"` - The canonical name of the agent that produced this item. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` -### Beta Response Mcp List Tools Completed Event + A file input to the model. -- `BetaResponseMcpListToolsCompletedEvent object { item_id, output_index, sequence_number, 2 more }` + - `type: "input_file"` - Emitted when the list of available MCP tools has been successfully retrieved. + The type of the input item. Always `input_file`. - - `item_id: string` + - `"input_file"` - The ID of the MCP tool call item that produced this output. + - `detail: optional "auto" or "low" or "high"` - - `output_index: number` + 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 index of the output item that was processed. + - `"auto"` - - `sequence_number: number` + - `"low"` - The sequence number of this event. + - `"high"` - - `type: "response.mcp_list_tools.completed"` + - `file_data: optional string` - The type of the event. Always 'response.mcp_list_tools.completed'. + The content of the file to be sent to the model. - - `"response.mcp_list_tools.completed"` + - `file_id: optional string` - - `agent: optional object { agent_name }` + The ID of the file to be sent to the model. - The agent that owns this multi-agent streaming event. + - `file_url: optional string` - - `agent_name: string` + The URL of the file to be sent to the model. - The canonical name of the agent that produced this item. + - `filename: optional string` -### Beta Response Mcp List Tools Failed Event + The name of the file to be sent to the model. -- `BetaResponseMcpListToolsFailedEvent object { item_id, output_index, sequence_number, 2 more }` + - `prompt_cache_breakpoint: optional object { mode }` - Emitted when the attempt to list available MCP tools has failed. + 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. - - `item_id: string` + - `mode: "explicit"` - The ID of the MCP tool call item that failed. + The breakpoint mode. Always `explicit`. - - `output_index: number` + - `"explicit"` - The index of the output item that failed. + - `role: "user" or "assistant" or "system" or "developer"` - - `sequence_number: number` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - The sequence number of this event. + - `"user"` - - `type: "response.mcp_list_tools.failed"` + - `"assistant"` - The type of the event. Always 'response.mcp_list_tools.failed'. + - `"system"` - - `"response.mcp_list_tools.failed"` + - `"developer"` - - `agent: optional object { agent_name }` + - `phase: optional "commentary" or "final_answer"` - The agent that owns this multi-agent streaming event. + 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. - - `agent_name: string` + - `"commentary"` - The canonical name of the agent that produced this item. + - `"final_answer"` -### Beta Response Mcp List Tools In Progress Event + - `type: optional "message"` -- `BetaResponseMcpListToolsInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + The type of the message input. Always `message`. - Emitted when the system is in the process of retrieving the list of available MCP tools. + - `"message"` - - `item_id: string` + - `Message object { content, role, agent, 2 more }` - The ID of the MCP tool call item that is being processed. + 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. - - `output_index: number` + - `content: BetaResponseInputMessageContentList` - The index of the output item that is being processed. + A list of one or many input items to the model, containing different content + types. - - `sequence_number: number` + - `role: "user" or "system" or "developer"` - The sequence number of this event. + The role of the message input. One of `user`, `system`, or `developer`. - - `type: "response.mcp_list_tools.in_progress"` + - `"user"` - The type of the event. Always 'response.mcp_list_tools.in_progress'. + - `"system"` - - `"response.mcp_list_tools.in_progress"` + - `"developer"` - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. -### Beta Response Output Audio - -- `BetaResponseOutputAudio object { data, transcript, type }` - - An audio output from the model. - - - `data: string` - - Base64-encoded audio data from the model. - - - `transcript: string` + - `status: optional "in_progress" or "completed" or "incomplete"` - The transcript of the audio data from the model. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `type: "output_audio"` + - `"in_progress"` - The type of the output audio. Always `output_audio`. + - `"completed"` - - `"output_audio"` + - `"incomplete"` -### Beta Response Output Item + - `type: optional "message"` -- `BetaResponseOutputItem = BetaResponseOutputMessage or object { id, queries, status, 3 more } or object { arguments, call_id, name, 6 more } or 28 more` + The type of the message input. Always set to `message`. - An output message from the model. + - `"message"` - `BetaResponseOutputMessage object { id, content, role, 4 more }` @@ -133167,66 +131128,36 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The text that was retrieved from the file. - - `FunctionCall object { arguments, call_id, name, 6 more }` + - `ComputerCall object { id, call_id, pending_safety_checks, 5 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. - - - `name: string` - - The name of the function to run. - - - `type: "function_call"` - - The type of the function tool call. Always `function_call`. - - - `"function_call"` - - - `id: optional string` - - The unique ID of the function tool call. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. - - - `Direct object { type }` - - - `type: "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` - - `"program"` + The type of the pending safety check. - - `namespace: optional string` + - `message: optional string` - The namespace of the function to run. + Details about the pending safety check. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `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. @@ -133237,371 +131168,308 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `FunctionCallOutput object { id, call_id, output, 5 more }` - - - `id: string` - - The unique ID of the function call tool output. - - - `call_id: string` - - The unique ID of the function tool call generated by the model. - - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - The output from the function call generated by your code. - Can be a string or an list of output content. - - - `StringOutput = string` - - A string of the output of the function call. - - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - Text, image, or file output of the function call. + - `type: "computer_call"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + The type of the computer call. Always `computer_call`. - A text input to the model. + - `"computer_call"` - - `text: string` + - `action: optional BetaComputerAction` - The text input to the model. + A click action. - - `type: "input_text"` + - `Click object { button, type, x, 2 more }` - The type of the input item. Always `input_text`. + A click action. - - `"input_text"` + - `button: "left" or "right" or "wheel" or 2 more` - - `prompt_cache_breakpoint: optional object { mode }` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - 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. + - `"left"` - - `mode: "explicit"` + - `"right"` - The breakpoint mode. Always `explicit`. + - `"wheel"` - - `"explicit"` + - `"back"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `"forward"` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `type: "click"` - - `detail: "low" or "high" or "auto" or "original"` + Specifies the event type. For a click action, this property is always `click`. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"click"` - - `"low"` + - `x: number` - - `"high"` + The x-coordinate where the click occurred. - - `"auto"` + - `y: number` - - `"original"` + The y-coordinate where the click occurred. - - `type: "input_image"` + - `keys: optional array of string` - The type of the input item. Always `input_image`. + The keys being held while clicking. - - `"input_image"` + - `DoubleClick object { keys, type, x, y }` - - `file_id: optional string` + A double click action. - The ID of the file to be sent to the model. + - `keys: array of string` - - `image_url: optional string` + The keys being held while double-clicking. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `type: "double_click"` - - `prompt_cache_breakpoint: optional object { mode }` + Specifies the event type. For a double click action, this property is always set to `double_click`. - 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. + - `"double_click"` - - `mode: "explicit"` + - `x: number` - The breakpoint mode. Always `explicit`. + The x-coordinate where the double click occurred. - - `"explicit"` + - `y: number` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + The y-coordinate where the double click occurred. - A file input to the model. + - `Drag object { path, type, keys }` - - `type: "input_file"` + A drag action. - The type of the input item. Always `input_file`. + - `path: array of object { x, y }` - - `"input_file"` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `detail: optional "auto" or "low" or "high"` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - 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`. + - `x: number` - - `"auto"` + The x-coordinate. - - `"low"` + - `y: number` - - `"high"` + The y-coordinate. - - `file_data: optional string` + - `type: "drag"` - The content of the file to be sent to the model. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `file_id: optional string` + - `"drag"` - The ID of the file to be sent to the model. + - `keys: optional array of string` - - `file_url: optional string` + The keys being held while dragging the mouse. - The URL of the file to be sent to the model. + - `Keypress object { keys, type }` - - `filename: optional string` + A collection of keypresses the model would like to perform. - The name of the file to be sent to the model. + - `keys: array of string` - - `prompt_cache_breakpoint: optional object { mode }` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - 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: "keypress"` - - `mode: "explicit"` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - The breakpoint mode. Always `explicit`. + - `"keypress"` - - `"explicit"` + - `Move object { type, x, y, keys }` - - `status: "in_progress" or "completed" or "incomplete"` + A mouse move action. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `type: "move"` - - `"in_progress"` + Specifies the event type. For a move action, this property is always set to `move`. - - `"completed"` + - `"move"` - - `"incomplete"` + - `x: number` - - `type: "function_call_output"` + The x-coordinate to move to. - The type of the function tool call output. Always `function_call_output`. + - `y: number` - - `"function_call_output"` + The y-coordinate to move to. - - `agent: optional object { agent_name }` + - `keys: optional array of string` - The agent that produced this item. + The keys being held while moving the mouse. - - `agent_name: string` + - `Screenshot object { type }` - The canonical name of the agent that produced this item. + A screenshot action. - - `caller: optional object { type } or object { caller_id, type }` + - `type: "screenshot"` - The execution context that produced this tool call. + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `Direct object { type }` + - `"screenshot"` - - `type: "direct"` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - The caller type. Always `direct`. + A scroll action. - - `"direct"` + - `scroll_x: number` - - `Program object { caller_id, type }` + The horizontal scroll distance. - - `caller_id: string` + - `scroll_y: number` - The call ID of the program item that produced this tool call. + The vertical scroll distance. - - `type: "program"` + - `type: "scroll"` - The caller type. Always `program`. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `"program"` + - `"scroll"` - - `created_by: optional string` + - `x: number` - The identifier of the actor that created the item. + The x-coordinate where the scroll occurred. - - `AgentMessage object { id, author, content, 3 more }` + - `y: number` - - `id: string` + The y-coordinate where the scroll occurred. - The unique ID of the agent message. + - `keys: optional array of string` - - `author: string` + The keys being held while scrolling. - The sending agent identity. + - `Type object { text, type }` - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + An action to type in text. - Encrypted content sent between agents. + - `text: string` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + The text to type. - A text input to the model. + - `type: "type"` - - `BetaResponseOutputText object { annotations, logprobs, text, type }` + Specifies the event type. For a type action, this property is always set to `type`. - A text output from the model. + - `"type"` - - `Text object { text, type }` + - `Wait object { type }` - A text content. + A wait action. - - `text: string` + - `type: "wait"` - - `type: "text"` + Specifies the event type. For a wait action, this property is always set to `wait`. - - `"text"` + - `"wait"` - - `SummaryText object { text, type }` + - `actions: optional BetaComputerActionList` - A summary text from the model. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `text: string` + - `Click object { button, type, x, 2 more }` - A summary of the reasoning output from the model so far. + A click action. - - `type: "summary_text"` + - `DoubleClick object { keys, type, x, y }` - The type of the object. Always `summary_text`. + A double click action. - - `"summary_text"` + - `Drag object { path, type, keys }` - - `ReasoningText object { text, type }` + A drag action. - Reasoning text from the model. + - `Keypress object { keys, type }` - - `text: string` + A collection of keypresses the model would like to perform. - The reasoning text from the model. + - `Move object { type, x, y, keys }` - - `type: "reasoning_text"` + A mouse move action. - The type of the reasoning text. Always `reasoning_text`. + - `Screenshot object { type }` - - `"reasoning_text"` + A screenshot action. - - `BetaResponseOutputRefusal object { refusal, type }` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - A refusal from the model. + A scroll action. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `Type object { text, type }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + An action to type in text. - - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` + - `Wait object { type }` - A screenshot of a computer. + A wait action. - - `detail: "low" or "high" or "auto" or "original"` + - `agent: optional object { agent_name }` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The agent that produced this item. - - `"low"` + - `agent_name: string` - - `"high"` + The canonical name of the agent that produced this item. - - `"auto"` + - `ComputerCallOutput object { call_id, output, type, 4 more }` - - `"original"` + The output of a computer tool call. - - `file_id: string` + - `call_id: string` - The identifier of an uploaded file that contains the screenshot. + The ID of the computer tool call that produced the output. - - `image_url: string` + - `output: BetaResponseComputerToolCallOutputScreenshot` - The URL of the screenshot image. + A computer screenshot image used with the computer use tool. - `type: "computer_screenshot"` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - `"computer_screenshot"` - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `"explicit"` - - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - A file input to the model. - - - `EncryptedContent object { encrypted_content, type }` - - Opaque encrypted content that Responses API decrypts inside trusted model execution. - - - `encrypted_content: string` - - Opaque encrypted content. - - - `type: "encrypted_content"` - - The type of the input item. Always `encrypted_content`. - - - `"encrypted_content"` + - `file_id: optional string` - - `recipient: string` + The identifier of an uploaded file that contains the screenshot. - The destination agent identity. + - `image_url: optional string` - - `type: "agent_message"` + The URL of the screenshot image. - The type of the item. Always `agent_message`. + - `type: "computer_call_output"` - - `"agent_message"` + The type of the computer tool call output. Always `computer_call_output`. - - `agent: optional object { agent_name }` + - `"computer_call_output"` - The agent that produced this item. + - `id: optional string` - - `agent_name: string` + The ID of the computer tool call output. - The canonical name of the agent that produced this item. + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `MultiAgentCall object { id, action, arguments, 3 more }` + The safety checks reported by the API that have been acknowledged by the developer. - `id: string` - The unique ID of the multi-agent call item. - - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - The multi-agent action to execute. - - - `"spawn_agent"` - - - `"interrupt_agent"` - - - `"list_agents"` - - - `"send_message"` - - - `"followup_task"` - - - `"wait_agent"` - - - `arguments: string` - - The JSON string of arguments generated for the action. - - - `call_id: string` + The ID of the pending safety check. - The unique ID linking this call to its output. + - `code: optional string` - - `type: "multi_agent_call"` + The type of the pending safety check. - The type of the multi-agent call. Always `multi_agent_call`. + - `message: optional string` - - `"multi_agent_call"` + Details about the pending safety check. - `agent: optional object { agent_name }` @@ -133611,63 +131479,15 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `MultiAgentCallOutput object { id, action, call_id, 3 more }` - - - `id: string` - - The unique ID of the multi-agent call output item. - - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - The multi-agent action that produced this result. - - - `"spawn_agent"` - - - `"interrupt_agent"` - - - `"list_agents"` - - - `"send_message"` - - - `"followup_task"` - - - `"wait_agent"` - - - `call_id: string` - - The unique ID of the multi-agent call. - - - `output: array of BetaResponseOutputText` - - Text output returned by the multi-agent action. - - - `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. - - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - - - `text: string` - - The text output from the model. - - - `type: "output_text"` - - The type of the output text. Always `output_text`. - - - `type: "multi_agent_call_output"` - - The type of the multi-agent result. Always `multi_agent_call_output`. - - - `"multi_agent_call_output"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `agent: optional object { agent_name }` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - The agent that produced this item. + - `"in_progress"` - - `agent_name: string` + - `"completed"` - The canonical name of the agent that produced this item. + - `"incomplete"` - `WebSearchCall object { id, action, status, 2 more }` @@ -133773,360 +131593,349 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + - `FunctionCall object { arguments, call_id, name, 6 more }` - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `id: string` + - `arguments: string` - The unique ID of the computer call. + A JSON string of the arguments to pass to the function. - `call_id: string` - An identifier used when responding to the tool call with output. - - - `pending_safety_checks: array of object { id, code, message }` + The unique ID of the function tool call generated by the model. - The pending safety checks for the computer call. + - `name: string` - - `id: string` + The name of the function to run. - The ID of the pending safety check. + - `type: "function_call"` - - `code: optional string` + The type of the function tool call. Always `function_call`. - The type of the pending safety check. + - `"function_call"` - - `message: optional string` + - `id: optional string` - Details about the pending safety check. + The unique ID of the function tool call. - - `status: "in_progress" or "completed" or "incomplete"` + - `agent: optional object { agent_name }` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The agent that produced this item. - - `"in_progress"` + - `agent_name: string` - - `"completed"` + The canonical name of the agent that produced this item. - - `"incomplete"` + - `caller: optional object { type } or object { caller_id, type }` - - `type: "computer_call"` + The execution context that produced this tool call. - The type of the computer call. Always `computer_call`. + - `Direct object { type }` - - `"computer_call"` + - `type: "direct"` - - `action: optional BetaComputerAction` + - `"direct"` - A click action. + - `Program object { caller_id, type }` - - `Click object { button, type, x, 2 more }` + - `caller_id: string` - A click action. + The call ID of the program item that produced this tool call. - - `button: "left" or "right" or "wheel" or 2 more` + - `type: "program"` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `"program"` - - `"left"` + - `namespace: optional string` - - `"right"` + The namespace of the function to run. - - `"wheel"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"back"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"forward"` + - `"in_progress"` - - `type: "click"` + - `"completed"` - Specifies the event type. For a click action, this property is always `click`. + - `"incomplete"` - - `"click"` + - `FunctionCallOutput object { call_id, output, type, 4 more }` - - `x: number` + The output of a function tool call. - The x-coordinate where the click occurred. + - `call_id: string` - - `y: number` + The unique ID of the function tool call generated by the model. - The y-coordinate where the click occurred. + - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - - `keys: optional array of string` + Text, image, or file output of the function tool call. - The keys being held while clicking. + - `string` - - `DoubleClick object { keys, type, x, y }` + A JSON string of the output of the function tool call. - A double click action. + - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - - `keys: array of string` + An array of content outputs (text, image, file) for the function tool call. - The keys being held while double-clicking. + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - - `type: "double_click"` + A text input to the model. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `text: string` - - `"double_click"` + The text input to the model. - - `x: number` + - `type: "input_text"` - The x-coordinate where the double click occurred. + The type of the input item. Always `input_text`. - - `y: number` + - `"input_text"` - The y-coordinate where the double click occurred. + - `prompt_cache_breakpoint: optional object { mode }` - - `Drag object { path, type, keys }` + 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 drag action. + - `mode: "explicit"` - - `path: array of object { x, y }` + The breakpoint mode. Always `explicit`. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `"explicit"` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - - `x: number` + An image input to the model. Learn about [image inputs](/docs/guides/vision) - The x-coordinate. + - `type: "input_image"` - - `y: number` + The type of the input item. Always `input_image`. - The y-coordinate. + - `"input_image"` - - `type: "drag"` + - `detail: optional "low" or "high" or "auto" or "original"` - Specifies the event type. For a drag action, this property is always set to `drag`. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"drag"` + - `"low"` - - `keys: optional array of string` + - `"high"` - The keys being held while dragging the mouse. + - `"auto"` - - `Keypress object { keys, type }` + - `"original"` - A collection of keypresses the model would like to perform. + - `file_id: optional string` - - `keys: array of string` + The ID of the file to be sent to the model. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `image_url: optional string` - - `type: "keypress"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `prompt_cache_breakpoint: optional object { mode }` - - `"keypress"` + 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. - - `Move object { type, x, y, keys }` + - `mode: "explicit"` - A mouse move action. + The breakpoint mode. Always `explicit`. - - `type: "move"` + - `"explicit"` - Specifies the event type. For a move action, this property is always set to `move`. + - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` - - `"move"` + A file input to the model. - - `x: number` + - `type: "input_file"` - The x-coordinate to move to. + The type of the input item. Always `input_file`. - - `y: number` + - `"input_file"` - The y-coordinate to move to. + - `detail: optional "auto" or "low" or "high"` - - `keys: optional array of string` + 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 keys being held while moving the mouse. + - `"auto"` - - `Screenshot object { type }` + - `"low"` - A screenshot action. + - `"high"` - - `type: "screenshot"` + - `file_data: optional string` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + The base64-encoded data of the file to be sent to the model. - - `"screenshot"` + - `file_id: optional string` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + The ID of the file to be sent to the model. - A scroll action. + - `file_url: optional string` - - `scroll_x: number` + The URL of the file to be sent to the model. - The horizontal scroll distance. + - `filename: optional string` - - `scroll_y: number` + The name of the file to be sent to the model. - The vertical scroll distance. + - `prompt_cache_breakpoint: optional object { mode }` - - `type: "scroll"` + 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. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `mode: "explicit"` - - `"scroll"` + The breakpoint mode. Always `explicit`. - - `x: number` + - `"explicit"` - The x-coordinate where the scroll occurred. + - `type: "function_call_output"` - - `y: number` + The type of the function tool call output. Always `function_call_output`. - The y-coordinate where the scroll occurred. + - `"function_call_output"` - - `keys: optional array of string` + - `id: optional string` - The keys being held while scrolling. + The unique ID of the function tool call output. Populated when this item is returned via API. - - `Type object { text, type }` + - `agent: optional object { agent_name }` - An action to type in text. + The agent that produced this item. - - `text: string` + - `agent_name: string` - The text to type. + The canonical name of the agent that produced this item. - - `type: "type"` + - `caller: optional object { type } or object { caller_id, type }` - Specifies the event type. For a type action, this property is always set to `type`. + The execution context that produced this tool call. - - `"type"` + - `Direct object { type }` - - `Wait object { type }` + - `type: "direct"` - A wait action. + The caller type. Always `direct`. - - `type: "wait"` + - `"direct"` - Specifies the event type. For a wait action, this property is always set to `wait`. + - `Program object { caller_id, type }` - - `"wait"` + - `caller_id: string` - - `actions: optional BetaComputerActionList` + The call ID of the program item that produced this tool call. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `type: "program"` - - `Click object { button, type, x, 2 more }` + The caller type. Always `program`. - A click action. + - `"program"` - - `DoubleClick object { keys, type, x, y }` + - `status: optional "in_progress" or "completed" or "incomplete"` - A double click action. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `Drag object { path, type, keys }` + - `"in_progress"` - A drag action. + - `"completed"` - - `Keypress object { keys, type }` + - `"incomplete"` - A collection of keypresses the model would like to perform. + - `AgentMessage object { author, content, recipient, 3 more }` - - `Move object { type, x, y, keys }` + A message routed between agents. - A mouse move action. + - `author: string` - - `Screenshot object { type }` + The sending agent identity. - A screenshot action. + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + Plaintext, image, or encrypted content sent between agents. - A scroll action. + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - - `Type object { text, type }` + A text input to the model. - An action to type in text. + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - - `Wait object { type }` + An image input to the model. Learn about [image inputs](/docs/guides/vision) - A wait action. + - `EncryptedContent object { encrypted_content, type }` - - `agent: optional object { agent_name }` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - The agent that produced this item. + - `encrypted_content: string` - - `agent_name: string` + Opaque encrypted content. - The canonical name of the agent that produced this item. + - `type: "encrypted_content"` - - `ComputerCallOutput object { id, call_id, output, 5 more }` + The type of the input item. Always `encrypted_content`. - - `id: string` + - `"encrypted_content"` - The unique ID of the computer call tool output. + - `recipient: string` - - `call_id: string` + The destination agent identity. - The ID of the computer tool call that produced the output. + - `type: "agent_message"` - - `output: BetaResponseComputerToolCallOutputScreenshot` + The item type. Always `agent_message`. - A computer screenshot image used with the computer use tool. + - `"agent_message"` - - `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 this agent message item. - - `"computer_screenshot"` + - `agent: optional object { agent_name }` - - `file_id: optional string` + The agent that produced this item. - The identifier of an uploaded file that contains the screenshot. + - `agent_name: string` - - `image_url: optional string` + The canonical name of the agent that produced this item. - The URL of the screenshot image. + - `MultiAgentCall object { action, arguments, call_id, 3 more }` - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The multi-agent action that was executed. - - `"completed"` + - `"spawn_agent"` - - `"incomplete"` + - `"interrupt_agent"` - - `"failed"` + - `"list_agents"` - - `"in_progress"` + - `"send_message"` - - `type: "computer_call_output"` + - `"followup_task"` - The type of the computer tool call output. Always `computer_call_output`. + - `"wait_agent"` - - `"computer_call_output"` + - `arguments: string` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + The action arguments as a JSON string. - The safety checks reported by the API that have been acknowledged by the - developer. + - `call_id: string` - - `id: string` + The unique ID linking this call to its output. - The ID of the pending safety check. + - `type: "multi_agent_call"` - - `code: optional string` + The item type. Always `multi_agent_call`. - The type of the pending safety check. + - `"multi_agent_call"` - - `message: optional string` + - `id: optional string` - Details about the pending safety check. + The unique ID of this multi-agent call. - `agent: optional object { agent_name }` @@ -134136,139 +131945,127 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` - - The identifier of the actor that created the item. - - - `Reasoning object { id, summary, type, 4 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). + - `MultiAgentCallOutput object { action, call_id, output, 3 more }` - - `id: string` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - The unique identifier of the reasoning content. + The multi-agent action that produced this result. - - `summary: array of object { text, type }` + - `"spawn_agent"` - Reasoning summary content. + - `"interrupt_agent"` - - `text: string` + - `"list_agents"` - A summary of the reasoning output from the model so far. + - `"send_message"` - - `type: "summary_text"` + - `"followup_task"` - The type of the object. Always `summary_text`. + - `"wait_agent"` - - `"summary_text"` + - `call_id: string` - - `type: "reasoning"` + The unique ID of the multi-agent call. - The type of the object. Always `reasoning`. + - `output: array of object { text, type, annotations }` - - `"reasoning"` + Text output returned by the multi-agent action. - - `agent: optional object { agent_name }` + - `text: string` - The agent that produced this item. + The text content. - - `agent_name: string` + - `type: "output_text"` - The canonical name of the agent that produced this item. + The content type. Always `output_text`. - - `content: optional array of object { text, type }` + - `"output_text"` - Reasoning text content. + - `annotations: optional 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 }` - - `text: string` + Citations associated with the text content. - The reasoning text from the model. + - `FileCitation object { file_id, filename, index, type }` - - `type: "reasoning_text"` + - `file_id: string` - The type of the reasoning text. Always `reasoning_text`. + The ID of the file. - - `"reasoning_text"` + - `filename: string` - - `encrypted_content: optional string` + The filename of the file cited. - 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. + - `index: number` - - `status: optional "in_progress" or "completed" or "incomplete"` + The index of the file in the list of files. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `type: "file_citation"` - - `"in_progress"` + The citation type. Always `file_citation`. - - `"completed"` + - `"file_citation"` - - `"incomplete"` + - `URLCitation object { end_index, start_index, title, 2 more }` - - `Program object { id, call_id, code, 3 more }` + - `end_index: number` - - `id: string` + The index of the last character of the citation in the message. - The unique ID of the program item. + - `start_index: number` - - `call_id: string` + The index of the first character of the citation in the message. - The stable call ID of the program item. + - `title: string` - - `code: string` + The title of the cited resource. - The JavaScript source executed by programmatic tool calling. + - `type: "url_citation"` - - `fingerprint: string` + The citation type. Always `url_citation`. - Opaque program replay fingerprint that must be round-tripped. + - `"url_citation"` - - `type: "program"` + - `url: string` - The type of the item. Always `program`. + The URL of the cited resource. - - `"program"` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - - `agent: optional object { agent_name }` + - `container_id: string` - The agent that produced this item. + The ID of the container. - - `agent_name: string` + - `end_index: number` - The canonical name of the agent that produced this item. + The index of the last character of the citation in the message. - - `ProgramOutput object { id, call_id, result, 3 more }` + - `file_id: string` - - `id: string` + The ID of the container file. - The unique ID of the program output item. + - `filename: string` - - `call_id: string` + The filename of the container file cited. - The call ID of the program item. + - `start_index: number` - - `result: string` + The index of the first character of the citation in the message. - The result produced by the program item. + - `type: "container_file_citation"` - - `status: "completed" or "incomplete"` + The citation type. Always `container_file_citation`. - The terminal status of the program output item. + - `"container_file_citation"` - - `"completed"` + - `type: "multi_agent_call_output"` - - `"incomplete"` + The item type. Always `multi_agent_call_output`. - - `type: "program_output"` + - `"multi_agent_call_output"` - The type of the item. Always `program_output`. + - `id: optional string` - - `"program_output"` + The unique ID of this multi-agent call output. - `agent: optional object { agent_name }` @@ -134278,44 +132075,22 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `ToolSearchCall object { id, arguments, call_id, 5 more }` - - - `id: string` - - The unique ID of the tool search call item. + - `ToolSearchCall object { arguments, type, id, 4 more }` - `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"` + The arguments supplied to the tool search call. - `type: "tool_search_call"` - The type of the item. Always `tool_search_call`. + The item type. Always `tool_search_call`. - `"tool_search_call"` + - `id: optional string` + + The unique ID of this tool search call. + - `agent: optional object { agent_name }` The agent that produced this item. @@ -134324,21 +132099,11 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` - - The identifier of the actor that created the item. - - - `ToolSearchOutput object { id, call_id, execution, 5 more }` - - - `id: string` - - The unique ID of the tool search output item. - - - `call_id: string` + - `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. @@ -134346,9 +132111,9 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"client"` - - `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 tool search call. - `"in_progress"` @@ -134356,9 +132121,11 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` + - `ToolSearchOutput object { tools, type, id, 4 more }` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - The loaded tool definitions returned by tool search. + The loaded tool definitions returned by the tool search output. - `Function object { name, parameters, strict, 5 more }` @@ -135501,10 +133268,14 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "tool_search_output"` - The type of the item. Always `tool_search_output`. + The item type. Always `tool_search_output`. - `"tool_search_output"` + - `id: optional string` + + The unique ID of this tool search output. + - `agent: optional object { agent_name }` The agent that produced this item. @@ -135513,39 +133284,39 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` + - `call_id: optional string` - The identifier of the actor that created the item. + The unique ID of the tool search call generated by the model. - - `AdditionalTools object { id, role, tools, 2 more }` + - `execution: optional "server" or "client"` - - `id: string` + Whether tool search was executed by the server or by the client. - The unique ID of the additional tools item. + - `"server"` - - `role: "unknown" or "user" or "assistant" or 5 more` + - `"client"` - The role that provided the additional tools. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"unknown"` + The status of the tool search output. - - `"user"` + - `"in_progress"` - - `"assistant"` + - `"completed"` - - `"system"` + - `"incomplete"` - - `"critic"` + - `AdditionalTools object { role, tools, type, 2 more }` - - `"discriminator"` + - `role: "developer"` - - `"developer"` + The role that provided the additional tools. Only `developer` is supported. - - `"tool"` + - `"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 }` @@ -136538,10 +134309,14 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "additional_tools"` - The type of the item. Always `additional_tools`. + The item type. Always `additional_tools`. - `"additional_tools"` + - `id: optional string` + + The unique ID of this additional tools item. + - `agent: optional object { agent_name }` The agent that produced this item. @@ -136550,17 +134325,83 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `Compaction object { id, encrypted_content, type, 2 more }` + - `Reasoning object { id, summary, type, 4 more }` - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + 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 object { text, type }` + + 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"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `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, agent }` + + 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"` @@ -136568,6 +134409,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"compaction"` + - `id: optional string` + + The ID of the compaction item. + - `agent: optional object { agent_name }` The agent that produced this item. @@ -136576,10 +134421,6 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` - - The identifier of the actor that created the item. - - `ImageGenerationCall object { id, result, status, 2 more }` An image generation request made by the model. @@ -136797,13 +134638,9 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `ShellCall object { id, action, call_id, 6 more }` - - A tool call that executes one or more shell commands in a managed environment. - - - `id: string` + - `ShellCall object { action, call_id, type, 5 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 }` @@ -136811,45 +134648,71 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `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: BetaResponseLocalEnvironment or BetaResponseContainerReference` + - `type: "shell_call"` - Represents the use of a local environment to perform shell actions. + The type of the item. Always `shell_call`. - - `BetaResponseLocalEnvironment object { type }` + - `"shell_call"` - Represents the use of a local environment to perform shell actions. + - `id: optional string` - - `type: "local"` + The unique ID of the shell tool call. Populated when this item is returned via API. - The environment type. Always `local`. + - `agent: optional object { agent_name }` - - `"local"` + The agent that produced this item. - - `BetaResponseContainerReference object { container_id, type }` + - `agent_name: string` - Represents a container created with /v1/containers. + The canonical name of the agent that produced this item. - - `container_id: string` + - `caller: optional object { type } or object { caller_id, type }` - - `type: "container_reference"` + The execution context that produced this tool call. - The environment type. Always `container_reference`. + - `Direct object { type }` - - `"container_reference"` + - `type: "direct"` - - `status: "in_progress" or "completed" or "incomplete"` + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + + - `environment: optional BetaLocalEnvironment or BetaContainerReference` + + The environment to execute the shell commands in. + + - `BetaLocalEnvironment object { type, skills }` + + - `BetaContainerReference object { container_id, type }` + + - `status: optional "in_progress" or "completed" or "incomplete"` The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. @@ -136859,11 +134722,63 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `type: "shell_call"` + - `ShellCallOutput object { call_id, output, type, 5 more }` - The type of the item. Always `shell_call`. + The streamed output items emitted by a shell tool call. - - `"shell_call"` + - `call_id: string` + + The unique ID of the shell tool call generated by the model. + + - `output: array of BetaResponseFunctionShellCallOutputContent` + + Captured chunks of stdout and stderr output, along with their associated outcomes. + + - `outcome: object { type } or object { exit_code, type }` + + The exit or timeout outcome associated with this shell call. + + - `Timeout object { type }` + + Indicates that the shell call exceeded its configured time limit. + + - `type: "timeout"` + + The outcome type. Always `timeout`. + + - `"timeout"` + + - `Exit object { exit_code, type }` + + Indicates that the shell commands finished and returned an exit code. + + - `exit_code: number` + + The exit code returned by the shell process. + + - `type: "exit"` + + The outcome type. Always `exit`. + + - `"exit"` + + - `stderr: string` + + Captured stderr output for the shell call. + + - `stdout: string` + + Captured stdout output for the shell call. + + - `type: "shell_call_output"` + + The type of the item. Always `shell_call_output`. + + - `"shell_call_output"` + + - `id: optional string` + + The unique ID of the shell tool call output. Populated when this item is returned via API. - `agent: optional object { agent_name }` @@ -136881,6 +134796,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "direct"` + The caller type. Always `direct`. + - `"direct"` - `Program object { caller_id, type }` @@ -136891,87 +134808,303 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "program"` + The caller type. Always `program`. + - `"program"` - - `created_by: optional string` + - `max_output_length: optional number` - The ID of the entity that created this tool call. + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` + - `status: optional "in_progress" or "completed" or "incomplete"` - The output of a shell tool call that was emitted. + The status of the shell call output. - - `id: string` + - `"in_progress"` - The unique ID of the shell call output. Populated when this item is returned via API. + - `"completed"` + + - `"incomplete"` + + - `ApplyPatchCall object { call_id, operation, status, 4 more }` + + A tool call representing a request to create, delete, or update files using diff patches. - `call_id: string` - The unique ID of the shell tool call generated by the model. + The unique ID of the apply patch tool call generated by the model. - - `max_output_length: number` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + The specific create, delete, or update instruction for the apply_patch tool call. - - `output: array of object { outcome, stderr, stdout, created_by }` + - `CreateFile object { diff, path, type }` - An array of shell call output contents + Instruction for creating a new file via the apply_patch tool. - - `outcome: object { type } or object { exit_code, type }` + - `diff: string` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + Unified diff content to apply when creating the file. - - `Timeout object { type }` + - `path: string` - Indicates that the shell call exceeded its configured time limit. + Path of the file to create relative to the workspace root. + + - `type: "create_file"` + + The operation type. Always `create_file`. + + - `"create_file"` + + - `DeleteFile object { path, type }` + + Instruction for deleting an existing file via the apply_patch tool. + + - `path: string` + + Path of the file to delete relative to the workspace root. + + - `type: "delete_file"` + + The operation type. Always `delete_file`. + + - `"delete_file"` + + - `UpdateFile object { diff, path, type }` + + Instruction for updating an existing file via the apply_patch tool. + + - `diff: string` + + Unified diff content to apply to the existing file. + + - `path: string` + + Path of the file to update relative to the workspace root. + + - `type: "update_file"` + + The operation type. Always `update_file`. + + - `"update_file"` + + - `status: "in_progress" or "completed"` + + The status of the apply patch tool call. One of `in_progress` or `completed`. + + - `"in_progress"` + + - `"completed"` + + - `type: "apply_patch_call"` + + The type of the item. Always `apply_patch_call`. + + - `"apply_patch_call"` + + - `id: optional string` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + + - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` + + The streamed output emitted by an apply patch tool call. + + - `call_id: string` + + The unique ID of the apply patch tool call generated by the model. + + - `status: "completed" or "failed"` + + The status of the apply patch tool call output. One of `completed` or `failed`. + + - `"completed"` + + - `"failed"` + + - `type: "apply_patch_call_output"` + + The type of the item. Always `apply_patch_call_output`. + + - `"apply_patch_call_output"` + + - `id: optional string` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + + - `output: optional string` + + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + + - `McpListTools object { id, server_label, tools, 3 more }` + + A list of tools available on an MCP server. + + - `id: string` + + The unique ID of the list. + + - `server_label: string` + + The label of the MCP server. + + - `tools: array of object { input_schema, name, annotations, description }` + + The tools available on the server. + + - `input_schema: unknown` + + The JSON schema describing the tool's input. + + - `name: string` + + The name of the tool. + + - `annotations: optional unknown` + + Additional annotations about the tool. + + - `description: optional string` + + The description of the tool. + + - `type: "mcp_list_tools"` + + The type of the item. Always `mcp_list_tools`. + + - `"mcp_list_tools"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `error: optional string` + + Error message if the server could not list tools. + + - `McpApprovalRequest object { id, arguments, name, 3 more }` + + A request for human approval of a tool invocation. + + - `id: string` + + The unique ID of the approval request. - - `type: "timeout"` + - `arguments: string` - The outcome type. Always `timeout`. + A JSON string of arguments for the tool. - - `"timeout"` + - `name: string` - - `Exit object { exit_code, type }` + The name of the tool to run. - Indicates that the shell commands finished and returned an exit code. + - `server_label: string` - - `exit_code: number` + The label of the MCP server making the request. - Exit code from the shell process. + - `type: "mcp_approval_request"` - - `type: "exit"` + The type of the item. Always `mcp_approval_request`. - The outcome type. Always `exit`. + - `"mcp_approval_request"` - - `"exit"` + - `agent: optional object { agent_name }` - - `stderr: string` + The agent that produced this item. - The standard error output that was captured. + - `agent_name: string` - - `stdout: string` + The canonical name of the agent that produced this item. - The standard output that was captured. + - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` - - `created_by: optional string` + A response to an MCP approval request. - The identifier of the actor that created the item. + - `approval_request_id: string` - - `status: "in_progress" or "completed" or "incomplete"` + The ID of the approval request being answered. - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `approve: boolean` - - `"in_progress"` + Whether the request was approved. - - `"completed"` + - `type: "mcp_approval_response"` - - `"incomplete"` + The type of the item. Always `mcp_approval_response`. - - `type: "shell_call_output"` + - `"mcp_approval_response"` - The type of the shell call output. Always `shell_call_output`. + - `id: optional string` - - `"shell_call_output"` + The unique ID of the approval response - `agent: optional object { agent_name }` @@ -136981,109 +135114,113 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` + - `reason: optional string` - The execution context that produced this tool call. + Optional reason for the decision. - - `Direct object { type }` + - `McpCall object { id, arguments, name, 7 more }` - - `type: "direct"` + An invocation of a tool on an MCP server. - - `"direct"` + - `id: string` - - `Program object { caller_id, type }` + The unique ID of the tool call. - - `caller_id: string` + - `arguments: string` - The call ID of the program item that produced this tool call. + A JSON string of the arguments passed to the tool. - - `type: "program"` + - `name: string` - - `"program"` + The name of the tool that was run. - - `created_by: optional string` + - `server_label: string` - The identifier of the actor that created the item. + The label of the MCP server running the tool. - - `ApplyPatchCall object { id, call_id, operation, 5 more }` + - `type: "mcp_call"` - A tool call that applies file diffs by creating, deleting, or updating files. + The type of the item. Always `mcp_call`. - - `id: string` + - `"mcp_call"` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `agent: optional object { agent_name }` - - `call_id: string` + The agent that produced this item. - The unique ID of the apply patch tool call generated by the model. + - `agent_name: string` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + The canonical name of the agent that produced this item. - One of the create_file, delete_file, or update_file operations applied via apply_patch. + - `approval_request_id: optional string` - - `CreateFile object { diff, path, type }` + 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. - Instruction describing how to create a file via the apply_patch tool. + - `error: optional string` - - `diff: string` + The error from the tool call, if any. - Diff to apply. + - `output: optional string` - - `path: string` + The output from the tool call. - Path of the file to create. + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `type: "create_file"` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - Create a new file with the provided diff. + - `"in_progress"` - - `"create_file"` + - `"completed"` - - `DeleteFile object { path, type }` + - `"incomplete"` - Instruction describing how to delete a file via the apply_patch tool. + - `"calling"` - - `path: string` + - `"failed"` - Path of the file to delete. + - `CustomToolCallOutput object { call_id, output, type, 3 more }` - - `type: "delete_file"` + The output of a custom tool call from your code, being sent back to the model. - Delete the specified file. + - `call_id: string` - - `"delete_file"` + The call ID, used to map this custom tool call output to a custom tool call. - - `UpdateFile object { diff, path, type }` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - Instruction describing how to update a file via the apply_patch tool. + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `diff: string` + - `StringOutput = string` - Diff to apply. + A string of the output of the custom tool call. - - `path: string` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - Path of the file to update. + Text, image, or file output of the custom tool call. - - `type: "update_file"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - Update an existing file with the provided diff. + A text input to the model. - - `"update_file"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `status: "in_progress" or "completed"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `"in_progress"` + A file input to the model. - - `"completed"` + - `type: "custom_tool_call_output"` - - `type: "apply_patch_call"` + The type of the custom tool call output. Always `custom_tool_call_output`. - The type of the item. Always `apply_patch_call`. + - `"custom_tool_call_output"` - - `"apply_patch_call"` + - `id: optional string` + + The unique ID of the custom tool call output in the OpenAI platform. - `agent: optional object { agent_name }` @@ -137101,6 +135238,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "direct"` + The caller type. Always `direct`. + - `"direct"` - `Program object { caller_id, type }` @@ -137111,37 +135250,35 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "program"` - - `"program"` - - - `created_by: optional string` + The caller type. Always `program`. - The ID of the entity that created this tool call. + - `"program"` - - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` + - `CustomToolCall object { call_id, input, name, 5 more }` - The output emitted by an apply patch tool call. + A call to a custom tool created by the model. - - `id: string` + - `call_id: string` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + An identifier used to map this custom tool call to a tool call output. - - `call_id: string` + - `input: string` - The unique ID of the apply patch tool call generated by the model. + The input for the custom tool call generated by the model. - - `status: "completed" or "failed"` + - `name: string` - The status of the apply patch tool call output. One of `completed` or `failed`. + The name of the custom tool being called. - - `"completed"` + - `type: "custom_tool_call"` - - `"failed"` + The type of the custom tool call. Always `custom_tool_call`. - - `type: "apply_patch_call_output"` + - `"custom_tool_call"` - The type of the item. Always `apply_patch_call_output`. + - `id: optional string` - - `"apply_patch_call_output"` + The unique ID of the custom tool call in the OpenAI platform. - `agent: optional object { agent_name }` @@ -137171,39 +135308,35 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"program"` - - `created_by: optional string` - - The ID of the entity that created this tool call output. - - - `output: optional string` + - `namespace: optional string` - Optional textual output returned by the apply patch tool. + The namespace of the custom tool being called. - - `McpCall object { id, arguments, name, 7 more }` + - `CompactionTrigger object { type, agent }` - An invocation of a tool on an MCP server. + Compacts the current context. Must be the final input item. - - `id: string` + - `type: "compaction_trigger"` - The unique ID of the tool call. + The type of the item. Always `compaction_trigger`. - - `arguments: string` + - `"compaction_trigger"` - A JSON string of the arguments passed to the tool. + - `agent: optional object { agent_name }` - - `name: string` + The agent that produced this item. - The name of the tool that was run. + - `agent_name: string` - - `server_label: string` + The canonical name of the agent that produced this item. - The label of the MCP server running the tool. + - `ItemReference object { id, agent, type }` - - `type: "mcp_call"` + An internal identifier for an item to reference. - The type of the item. Always `mcp_call`. + - `id: string` - - `"mcp_call"` + The ID of the item to reference. - `agent: optional object { agent_name }` @@ -137213,70 +135346,71 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `approval_request_id: optional string` + - `type: optional "item_reference"` - 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 type of item to reference. Always `item_reference`. - - `error: optional string` + - `"item_reference"` - The error from the tool call, if any. + - `Program object { id, call_id, code, 3 more }` - - `output: optional string` + - `id: string` - The output from the tool call. + The unique ID of this program item. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `call_id: string` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The stable call ID of the program item. - - `"in_progress"` + - `code: string` - - `"completed"` + The JavaScript source executed by programmatic tool calling. - - `"incomplete"` + - `fingerprint: string` - - `"calling"` + Opaque program replay fingerprint that must be round-tripped. - - `"failed"` + - `type: "program"` - - `McpListTools object { id, server_label, tools, 3 more }` + The item type. Always `program`. - A list of tools available on an MCP server. + - `"program"` - - `id: string` + - `agent: optional object { agent_name }` - The unique ID of the list. + The agent that produced this item. - - `server_label: string` + - `agent_name: string` - The label of the MCP server. + The canonical name of the agent that produced this item. - - `tools: array of object { input_schema, name, annotations, description }` + - `ProgramOutput object { id, call_id, result, 3 more }` - The tools available on the server. + - `id: string` - - `input_schema: unknown` + The unique ID of this program output item. - The JSON schema describing the tool's input. + - `call_id: string` - - `name: string` + The call ID of the program item. - The name of the tool. + - `result: string` - - `annotations: optional unknown` + The result produced by the program item. - Additional annotations about the tool. + - `status: "completed" or "incomplete"` - - `description: optional string` + The terminal status of the program output. - The description of the tool. + - `"completed"` - - `type: "mcp_list_tools"` + - `"incomplete"` - The type of the item. Always `mcp_list_tools`. + - `type: "program_output"` - - `"mcp_list_tools"` + The item type. Always `program_output`. + + - `"program_output"` - `agent: optional object { agent_name }` @@ -137286,233 +135420,250 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `error: optional string` + - `response_id: string` - Error message if the server could not list tools. + The ID of the active response that should receive the input. - - `McpApprovalRequest object { id, arguments, name, 3 more }` + - `type: "response.inject"` - A request for human approval of a tool invocation. + The event discriminator. Always `response.inject`. - - `id: string` + - `"response.inject"` - The unique ID of the approval request. +### Beta Response Inject Failed Event - - `arguments: string` +- `BetaResponseInjectFailedEvent object { error, input, response_id, 3 more }` - A JSON string of arguments for the tool. + Emitted when injected input could not be committed to a response. The event + returns the uncommitted raw input so the client can retry it in another + response when appropriate. - - `name: string` + - `error: object { code, message }` - The name of the tool to run. + Information about why the input was not committed. - - `server_label: string` + - `code: "response_already_completed" or "response_not_found"` - The label of the MCP server making the request. + A machine-readable error code. - - `type: "mcp_approval_request"` + - `"response_already_completed"` - The type of the item. Always `mcp_approval_request`. + - `"response_not_found"` - - `"mcp_approval_request"` + - `message: string` - - `agent: optional object { agent_name }` + A human-readable description of the error. - The agent that produced this item. + - `input: array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - - `agent_name: string` + The raw input items that were not committed. - The canonical name of the agent that produced this item. + - `BetaEasyInputMessage object { content, role, phase, type }` - - `McpApprovalResponse object { id, approval_request_id, approve, 3 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. - A response to an MCP approval request. + - `content: string or BetaResponseInputMessageContentList` - - `id: string` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - The unique ID of the approval response + - `TextInput = string` - - `approval_request_id: string` + A text input to the model. - The ID of the approval request being answered. + - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` - - `approve: boolean` + A list of one or many input items to the model, containing different content + types. - Whether the request was approved. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `type: "mcp_approval_response"` + A text input to the model. - The type of the item. Always `mcp_approval_response`. + - `text: string` - - `"mcp_approval_response"` + The text input to the model. - - `agent: optional object { agent_name }` + - `type: "input_text"` - The agent that produced this item. + The type of the input item. Always `input_text`. - - `agent_name: string` + - `"input_text"` - The canonical name of the agent that produced this item. + - `prompt_cache_breakpoint: optional object { mode }` - - `reason: 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. - Optional reason for the decision. + - `mode: "explicit"` - - `CustomToolCall object { call_id, input, name, 5 more }` + The breakpoint mode. Always `explicit`. - A call to a custom tool created by the model. + - `"explicit"` - - `call_id: string` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - An identifier used to map this custom tool call to a tool call output. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `input: string` + - `detail: "low" or "high" or "auto" or "original"` - The input for the custom tool call generated by the model. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `name: string` + - `"low"` - The name of the custom tool being called. + - `"high"` - - `type: "custom_tool_call"` + - `"auto"` - The type of the custom tool call. Always `custom_tool_call`. + - `"original"` - - `"custom_tool_call"` + - `type: "input_image"` - - `id: optional string` + The type of the input item. Always `input_image`. - The unique ID of the custom tool call in the OpenAI platform. + - `"input_image"` - - `agent: optional object { agent_name }` + - `file_id: optional string` - The agent that produced this item. + The ID of the file to be sent to the model. - - `agent_name: string` + - `image_url: optional string` - The canonical name of the agent that produced this item. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `caller: optional object { type } or object { caller_id, type }` + - `prompt_cache_breakpoint: optional object { mode }` - The execution context that produced this tool call. + 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. - - `Direct object { type }` + - `mode: "explicit"` - - `type: "direct"` + The breakpoint mode. Always `explicit`. - - `"direct"` + - `"explicit"` - - `Program object { caller_id, type }` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `caller_id: string` + A file input to the model. - The call ID of the program item that produced this tool call. + - `type: "input_file"` - - `type: "program"` + The type of the input item. Always `input_file`. - - `"program"` + - `"input_file"` - - `namespace: optional string` + - `detail: optional "auto" or "low" or "high"` - The namespace of the custom tool being called. + 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`. - - `CustomToolCallOutput object { id, call_id, output, 5 more }` + - `"auto"` - - `id: string` + - `"low"` - The unique ID of the custom tool call output item. + - `"high"` - - `call_id: string` + - `file_data: optional string` - The call ID, used to map this custom tool call output to a custom tool call. + The content of the file to be sent to the model. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `file_id: optional string` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + The ID of the file to be sent to the model. - - `StringOutput = string` + - `file_url: optional string` - A string of the output of the custom tool call. + The URL of the file to be sent to the model. - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `filename: optional string` - Text, image, or file output of the custom tool call. + The name of the file to be sent to the model. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `prompt_cache_breakpoint: optional object { mode }` - A text input to the model. + 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. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `mode: "explicit"` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + The breakpoint mode. Always `explicit`. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `"explicit"` - A file input to the model. + - `role: "user" or "assistant" or "system" or "developer"` - - `status: "in_progress" or "completed" or "incomplete"` + The role of the message input. One of `user`, `assistant`, `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"` + - `"assistant"` - - `"completed"` + - `"system"` - - `"incomplete"` + - `"developer"` - - `type: "custom_tool_call_output"` + - `phase: optional "commentary" or "final_answer"` - The type of the custom tool call output. Always `custom_tool_call_output`. + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - - `"custom_tool_call_output"` + - `"commentary"` - - `agent: optional object { agent_name }` + - `"final_answer"` - The agent that produced this item. + - `type: optional "message"` - - `agent_name: string` + The type of the message input. Always `message`. - The canonical name of the agent that produced this item. + - `"message"` - - `caller: optional object { type } or object { caller_id, type }` + - `Message object { content, role, agent, 2 more }` - The execution context 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. - - `Direct object { type }` + - `content: BetaResponseInputMessageContentList` - - `type: "direct"` + A list of one or many input items to the model, containing different content + types. - The caller type. Always `direct`. + - `role: "user" or "system" or "developer"` - - `"direct"` + The role of the message input. One of `user`, `system`, or `developer`. - - `Program object { caller_id, type }` + - `"user"` - - `caller_id: string` + - `"system"` - The call ID of the program item that produced this tool call. + - `"developer"` - - `type: "program"` + - `agent: optional object { agent_name }` - The caller type. Always `program`. + The agent that produced this item. - - `"program"` + - `agent_name: string` - - `created_by: optional string` + The canonical name of the agent that produced this item. - The identifier of the actor that created the item. + - `status: optional "in_progress" or "completed" or "incomplete"` -### Beta Response Output Item Added Event + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. -- `BetaResponseOutputItemAddedEvent object { item, output_index, sequence_number, 2 more }` + - `"in_progress"` - Emitted when a new output item is added. + - `"completed"` - - `item: BetaResponseOutputItem` + - `"incomplete"` - The output item that was added. + - `type: optional "message"` + + The type of the message input. Always set to `message`. + + - `"message"` - `BetaResponseOutputMessage object { id, content, role, 4 more }` @@ -137787,66 +135938,36 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The text that was retrieved from the file. - - `FunctionCall object { arguments, call_id, name, 6 more }` + - `ComputerCall object { id, call_id, pending_safety_checks, 5 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. - - - `name: string` - - The name of the function to run. - - - `type: "function_call"` - - The type of the function tool call. Always `function_call`. - - - `"function_call"` - - - `id: optional string` - - The unique ID of the function tool call. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. - - - `Direct object { type }` - - - `type: "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` - - `"program"` + The type of the pending safety check. - - `namespace: optional string` + - `message: optional string` - The namespace of the function to run. + Details about the pending safety check. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `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. @@ -137857,371 +135978,308 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `FunctionCallOutput object { id, call_id, output, 5 more }` - - - `id: string` - - The unique ID of the function call tool output. - - - `call_id: string` - - The unique ID of the function tool call generated by the model. - - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - The output from the function call generated by your code. - Can be a string or an list of output content. - - - `StringOutput = string` - - A string of the output of the function call. - - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - Text, image, or file output of the function call. + - `type: "computer_call"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + The type of the computer call. Always `computer_call`. - A text input to the model. + - `"computer_call"` - - `text: string` + - `action: optional BetaComputerAction` - The text input to the model. + A click action. - - `type: "input_text"` + - `Click object { button, type, x, 2 more }` - The type of the input item. Always `input_text`. + A click action. - - `"input_text"` + - `button: "left" or "right" or "wheel" or 2 more` - - `prompt_cache_breakpoint: optional object { mode }` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - 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. + - `"left"` - - `mode: "explicit"` + - `"right"` - The breakpoint mode. Always `explicit`. + - `"wheel"` - - `"explicit"` + - `"back"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `"forward"` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `type: "click"` - - `detail: "low" or "high" or "auto" or "original"` + Specifies the event type. For a click action, this property is always `click`. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"click"` - - `"low"` + - `x: number` - - `"high"` + The x-coordinate where the click occurred. - - `"auto"` + - `y: number` - - `"original"` + The y-coordinate where the click occurred. - - `type: "input_image"` + - `keys: optional array of string` - The type of the input item. Always `input_image`. + The keys being held while clicking. - - `"input_image"` + - `DoubleClick object { keys, type, x, y }` - - `file_id: optional string` + A double click action. - The ID of the file to be sent to the model. + - `keys: array of string` - - `image_url: optional string` + The keys being held while double-clicking. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `type: "double_click"` - - `prompt_cache_breakpoint: optional object { mode }` + Specifies the event type. For a double click action, this property is always set to `double_click`. - 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. + - `"double_click"` - - `mode: "explicit"` + - `x: number` - The breakpoint mode. Always `explicit`. + The x-coordinate where the double click occurred. - - `"explicit"` + - `y: number` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + The y-coordinate where the double click occurred. - A file input to the model. + - `Drag object { path, type, keys }` - - `type: "input_file"` + A drag action. - The type of the input item. Always `input_file`. + - `path: array of object { x, y }` - - `"input_file"` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `detail: optional "auto" or "low" or "high"` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - 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`. + - `x: number` - - `"auto"` + The x-coordinate. - - `"low"` + - `y: number` - - `"high"` + The y-coordinate. - - `file_data: optional string` + - `type: "drag"` - The content of the file to be sent to the model. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `file_id: optional string` + - `"drag"` - The ID of the file to be sent to the model. + - `keys: optional array of string` - - `file_url: optional string` + The keys being held while dragging the mouse. - The URL of the file to be sent to the model. + - `Keypress object { keys, type }` - - `filename: optional string` + A collection of keypresses the model would like to perform. - The name of the file to be sent to the model. + - `keys: array of string` - - `prompt_cache_breakpoint: optional object { mode }` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - 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: "keypress"` - - `mode: "explicit"` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - The breakpoint mode. Always `explicit`. + - `"keypress"` - - `"explicit"` + - `Move object { type, x, y, keys }` - - `status: "in_progress" or "completed" or "incomplete"` + A mouse move action. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `type: "move"` - - `"in_progress"` + Specifies the event type. For a move action, this property is always set to `move`. - - `"completed"` + - `"move"` - - `"incomplete"` + - `x: number` - - `type: "function_call_output"` + The x-coordinate to move to. - The type of the function tool call output. Always `function_call_output`. + - `y: number` - - `"function_call_output"` + The y-coordinate to move to. - - `agent: optional object { agent_name }` + - `keys: optional array of string` - The agent that produced this item. + The keys being held while moving the mouse. - - `agent_name: string` + - `Screenshot object { type }` - The canonical name of the agent that produced this item. + A screenshot action. - - `caller: optional object { type } or object { caller_id, type }` + - `type: "screenshot"` - The execution context that produced this tool call. + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `Direct object { type }` + - `"screenshot"` - - `type: "direct"` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - The caller type. Always `direct`. + A scroll action. - - `"direct"` + - `scroll_x: number` - - `Program object { caller_id, type }` + The horizontal scroll distance. - - `caller_id: string` + - `scroll_y: number` - The call ID of the program item that produced this tool call. + The vertical scroll distance. - - `type: "program"` + - `type: "scroll"` - The caller type. Always `program`. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `"program"` + - `"scroll"` - - `created_by: optional string` + - `x: number` - The identifier of the actor that created the item. + The x-coordinate where the scroll occurred. - - `AgentMessage object { id, author, content, 3 more }` + - `y: number` - - `id: string` + The y-coordinate where the scroll occurred. - The unique ID of the agent message. + - `keys: optional array of string` - - `author: string` + The keys being held while scrolling. - The sending agent identity. + - `Type object { text, type }` - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + An action to type in text. - Encrypted content sent between agents. + - `text: string` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + The text to type. - A text input to the model. + - `type: "type"` - - `BetaResponseOutputText object { annotations, logprobs, text, type }` + Specifies the event type. For a type action, this property is always set to `type`. - A text output from the model. + - `"type"` - - `Text object { text, type }` + - `Wait object { type }` - A text content. + A wait action. - - `text: string` + - `type: "wait"` - - `type: "text"` + Specifies the event type. For a wait action, this property is always set to `wait`. - - `"text"` + - `"wait"` - - `SummaryText object { text, type }` + - `actions: optional BetaComputerActionList` - A summary text from the model. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `text: string` + - `Click object { button, type, x, 2 more }` - A summary of the reasoning output from the model so far. + A click action. - - `type: "summary_text"` + - `DoubleClick object { keys, type, x, y }` - The type of the object. Always `summary_text`. + A double click action. - - `"summary_text"` + - `Drag object { path, type, keys }` - - `ReasoningText object { text, type }` + A drag action. - Reasoning text from the model. + - `Keypress object { keys, type }` - - `text: string` + A collection of keypresses the model would like to perform. - The reasoning text from the model. + - `Move object { type, x, y, keys }` - - `type: "reasoning_text"` + A mouse move action. - The type of the reasoning text. Always `reasoning_text`. + - `Screenshot object { type }` - - `"reasoning_text"` + A screenshot action. - - `BetaResponseOutputRefusal object { refusal, type }` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - A refusal from the model. + A scroll action. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `Type object { text, type }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + An action to type in text. - - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` + - `Wait object { type }` - A screenshot of a computer. + A wait action. - - `detail: "low" or "high" or "auto" or "original"` + - `agent: optional object { agent_name }` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The agent that produced this item. - - `"low"` + - `agent_name: string` - - `"high"` + The canonical name of the agent that produced this item. - - `"auto"` + - `ComputerCallOutput object { call_id, output, type, 4 more }` - - `"original"` + The output of a computer tool call. - - `file_id: string` + - `call_id: string` - The identifier of an uploaded file that contains the screenshot. + The ID of the computer tool call that produced the output. - - `image_url: string` + - `output: BetaResponseComputerToolCallOutputScreenshot` - The URL of the screenshot image. + A computer screenshot image used with the computer use tool. - `type: "computer_screenshot"` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - `"computer_screenshot"` - - `prompt_cache_breakpoint: optional object { mode }` - - Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. - - - `mode: "explicit"` - - The breakpoint mode. Always `explicit`. - - - `"explicit"` - - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - A file input to the model. - - - `EncryptedContent object { encrypted_content, type }` - - Opaque encrypted content that Responses API decrypts inside trusted model execution. - - - `encrypted_content: string` - - Opaque encrypted content. - - - `type: "encrypted_content"` - - The type of the input item. Always `encrypted_content`. - - - `"encrypted_content"` + - `file_id: optional string` - - `recipient: string` + The identifier of an uploaded file that contains the screenshot. - The destination agent identity. + - `image_url: optional string` - - `type: "agent_message"` + The URL of the screenshot image. - The type of the item. Always `agent_message`. + - `type: "computer_call_output"` - - `"agent_message"` + The type of the computer tool call output. Always `computer_call_output`. - - `agent: optional object { agent_name }` + - `"computer_call_output"` - The agent that produced this item. + - `id: optional string` - - `agent_name: string` + The ID of the computer tool call output. - The canonical name of the agent that produced this item. + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `MultiAgentCall object { id, action, arguments, 3 more }` + The safety checks reported by the API that have been acknowledged by the developer. - `id: string` - The unique ID of the multi-agent call item. - - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - The multi-agent action to execute. - - - `"spawn_agent"` - - - `"interrupt_agent"` - - - `"list_agents"` - - - `"send_message"` - - - `"followup_task"` - - - `"wait_agent"` - - - `arguments: string` - - The JSON string of arguments generated for the action. - - - `call_id: string` + The ID of the pending safety check. - The unique ID linking this call to its output. + - `code: optional string` - - `type: "multi_agent_call"` + The type of the pending safety check. - The type of the multi-agent call. Always `multi_agent_call`. + - `message: optional string` - - `"multi_agent_call"` + Details about the pending safety check. - `agent: optional object { agent_name }` @@ -138231,63 +136289,15 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `MultiAgentCallOutput object { id, action, call_id, 3 more }` - - - `id: string` - - The unique ID of the multi-agent call output item. - - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - The multi-agent action that produced this result. - - - `"spawn_agent"` - - - `"interrupt_agent"` - - - `"list_agents"` - - - `"send_message"` - - - `"followup_task"` - - - `"wait_agent"` - - - `call_id: string` - - The unique ID of the multi-agent call. - - - `output: array of BetaResponseOutputText` - - Text output returned by the multi-agent action. - - - `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. - - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - - - `text: string` - - The text output from the model. - - - `type: "output_text"` - - The type of the output text. Always `output_text`. - - - `type: "multi_agent_call_output"` - - The type of the multi-agent result. Always `multi_agent_call_output`. - - - `"multi_agent_call_output"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `agent: optional object { agent_name }` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - The agent that produced this item. + - `"in_progress"` - - `agent_name: string` + - `"completed"` - The canonical name of the agent that produced this item. + - `"incomplete"` - `WebSearchCall object { id, action, status, 2 more }` @@ -138393,360 +136403,349 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + - `FunctionCall object { arguments, call_id, name, 6 more }` - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `id: string` + - `arguments: string` - The unique ID of the computer call. + A JSON string of the arguments to pass to the function. - `call_id: string` - An identifier used when responding to the tool call with output. - - - `pending_safety_checks: array of object { id, code, message }` + The unique ID of the function tool call generated by the model. - The pending safety checks for the computer call. + - `name: string` - - `id: string` + The name of the function to run. - The ID of the pending safety check. + - `type: "function_call"` - - `code: optional string` + The type of the function tool call. Always `function_call`. - The type of the pending safety check. + - `"function_call"` - - `message: optional string` + - `id: optional string` - Details about the pending safety check. + The unique ID of the function tool call. - - `status: "in_progress" or "completed" or "incomplete"` + - `agent: optional object { agent_name }` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The agent that produced this item. - - `"in_progress"` + - `agent_name: string` - - `"completed"` + The canonical name of the agent that produced this item. - - `"incomplete"` + - `caller: optional object { type } or object { caller_id, type }` - - `type: "computer_call"` + The execution context that produced this tool call. - The type of the computer call. Always `computer_call`. + - `Direct object { type }` - - `"computer_call"` + - `type: "direct"` - - `action: optional BetaComputerAction` + - `"direct"` - A click action. + - `Program object { caller_id, type }` - - `Click object { button, type, x, 2 more }` + - `caller_id: string` - A click action. + The call ID of the program item that produced this tool call. - - `button: "left" or "right" or "wheel" or 2 more` + - `type: "program"` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `"program"` - - `"left"` + - `namespace: optional string` - - `"right"` + The namespace of the function to run. - - `"wheel"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"back"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"forward"` + - `"in_progress"` - - `type: "click"` + - `"completed"` - Specifies the event type. For a click action, this property is always `click`. + - `"incomplete"` - - `"click"` + - `FunctionCallOutput object { call_id, output, type, 4 more }` - - `x: number` + The output of a function tool call. - The x-coordinate where the click occurred. + - `call_id: string` - - `y: number` + The unique ID of the function tool call generated by the model. - The y-coordinate where the click occurred. + - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - - `keys: optional array of string` + Text, image, or file output of the function tool call. - The keys being held while clicking. + - `string` - - `DoubleClick object { keys, type, x, y }` + A JSON string of the output of the function tool call. - A double click action. + - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - - `keys: array of string` + An array of content outputs (text, image, file) for the function tool call. - The keys being held while double-clicking. + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - - `type: "double_click"` + A text input to the model. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `text: string` - - `"double_click"` + The text input to the model. - - `x: number` + - `type: "input_text"` - The x-coordinate where the double click occurred. + The type of the input item. Always `input_text`. - - `y: number` + - `"input_text"` - The y-coordinate where the double click occurred. + - `prompt_cache_breakpoint: optional object { mode }` - - `Drag object { path, type, keys }` + 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 drag action. + - `mode: "explicit"` - - `path: array of object { x, y }` + The breakpoint mode. Always `explicit`. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `"explicit"` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - - `x: number` + An image input to the model. Learn about [image inputs](/docs/guides/vision) - The x-coordinate. + - `type: "input_image"` - - `y: number` + The type of the input item. Always `input_image`. - The y-coordinate. + - `"input_image"` - - `type: "drag"` + - `detail: optional "low" or "high" or "auto" or "original"` - Specifies the event type. For a drag action, this property is always set to `drag`. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"drag"` + - `"low"` - - `keys: optional array of string` + - `"high"` - The keys being held while dragging the mouse. + - `"auto"` - - `Keypress object { keys, type }` + - `"original"` - A collection of keypresses the model would like to perform. + - `file_id: optional string` - - `keys: array of string` + The ID of the file to be sent to the model. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `image_url: optional string` - - `type: "keypress"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `prompt_cache_breakpoint: optional object { mode }` - - `"keypress"` + 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. - - `Move object { type, x, y, keys }` + - `mode: "explicit"` - A mouse move action. + The breakpoint mode. Always `explicit`. - - `type: "move"` + - `"explicit"` - Specifies the event type. For a move action, this property is always set to `move`. + - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` - - `"move"` + A file input to the model. - - `x: number` + - `type: "input_file"` - The x-coordinate to move to. + The type of the input item. Always `input_file`. - - `y: number` + - `"input_file"` - The y-coordinate to move to. + - `detail: optional "auto" or "low" or "high"` - - `keys: optional array of string` + 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 keys being held while moving the mouse. + - `"auto"` - - `Screenshot object { type }` + - `"low"` - A screenshot action. + - `"high"` - - `type: "screenshot"` + - `file_data: optional string` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + The base64-encoded data of the file to be sent to the model. - - `"screenshot"` + - `file_id: optional string` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + The ID of the file to be sent to the model. - A scroll action. + - `file_url: optional string` - - `scroll_x: number` + The URL of the file to be sent to the model. - The horizontal scroll distance. + - `filename: optional string` - - `scroll_y: number` + The name of the file to be sent to the model. - The vertical scroll distance. + - `prompt_cache_breakpoint: optional object { mode }` - - `type: "scroll"` + 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. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `mode: "explicit"` - - `"scroll"` + The breakpoint mode. Always `explicit`. - - `x: number` + - `"explicit"` - The x-coordinate where the scroll occurred. + - `type: "function_call_output"` - - `y: number` + The type of the function tool call output. Always `function_call_output`. - The y-coordinate where the scroll occurred. + - `"function_call_output"` - - `keys: optional array of string` + - `id: optional string` - The keys being held while scrolling. + The unique ID of the function tool call output. Populated when this item is returned via API. - - `Type object { text, type }` + - `agent: optional object { agent_name }` - An action to type in text. + The agent that produced this item. - - `text: string` + - `agent_name: string` - The text to type. + The canonical name of the agent that produced this item. - - `type: "type"` + - `caller: optional object { type } or object { caller_id, type }` - Specifies the event type. For a type action, this property is always set to `type`. + The execution context that produced this tool call. - - `"type"` + - `Direct object { type }` - - `Wait object { type }` + - `type: "direct"` - A wait action. + The caller type. Always `direct`. - - `type: "wait"` + - `"direct"` - Specifies the event type. For a wait action, this property is always set to `wait`. + - `Program object { caller_id, type }` - - `"wait"` + - `caller_id: string` - - `actions: optional BetaComputerActionList` + The call ID of the program item that produced this tool call. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `type: "program"` - - `Click object { button, type, x, 2 more }` + The caller type. Always `program`. - A click action. + - `"program"` - - `DoubleClick object { keys, type, x, y }` + - `status: optional "in_progress" or "completed" or "incomplete"` - A double click action. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `Drag object { path, type, keys }` + - `"in_progress"` - A drag action. + - `"completed"` - - `Keypress object { keys, type }` + - `"incomplete"` - A collection of keypresses the model would like to perform. + - `AgentMessage object { author, content, recipient, 3 more }` - - `Move object { type, x, y, keys }` + A message routed between agents. - A mouse move action. + - `author: string` - - `Screenshot object { type }` + The sending agent identity. - A screenshot action. + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + Plaintext, image, or encrypted content sent between agents. - A scroll action. + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - - `Type object { text, type }` + A text input to the model. - An action to type in text. + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - - `Wait object { type }` + An image input to the model. Learn about [image inputs](/docs/guides/vision) - A wait action. + - `EncryptedContent object { encrypted_content, type }` - - `agent: optional object { agent_name }` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - The agent that produced this item. + - `encrypted_content: string` - - `agent_name: string` + Opaque encrypted content. - The canonical name of the agent that produced this item. + - `type: "encrypted_content"` - - `ComputerCallOutput object { id, call_id, output, 5 more }` + The type of the input item. Always `encrypted_content`. - - `id: string` + - `"encrypted_content"` - The unique ID of the computer call tool output. + - `recipient: string` - - `call_id: string` + The destination agent identity. - The ID of the computer tool call that produced the output. + - `type: "agent_message"` - - `output: BetaResponseComputerToolCallOutputScreenshot` + The item type. Always `agent_message`. - A computer screenshot image used with the computer use tool. + - `"agent_message"` - - `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 this agent message item. - - `"computer_screenshot"` + - `agent: optional object { agent_name }` - - `file_id: optional string` + The agent that produced this item. - The identifier of an uploaded file that contains the screenshot. + - `agent_name: string` - - `image_url: optional string` + The canonical name of the agent that produced this item. - The URL of the screenshot image. + - `MultiAgentCall object { action, arguments, call_id, 3 more }` - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The multi-agent action that was executed. - - `"completed"` + - `"spawn_agent"` - - `"incomplete"` + - `"interrupt_agent"` - - `"failed"` + - `"list_agents"` - - `"in_progress"` + - `"send_message"` - - `type: "computer_call_output"` + - `"followup_task"` - The type of the computer tool call output. Always `computer_call_output`. + - `"wait_agent"` - - `"computer_call_output"` + - `arguments: string` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + The action arguments as a JSON string. - The safety checks reported by the API that have been acknowledged by the - developer. + - `call_id: string` - - `id: string` + The unique ID linking this call to its output. - The ID of the pending safety check. + - `type: "multi_agent_call"` - - `code: optional string` + The item type. Always `multi_agent_call`. - The type of the pending safety check. + - `"multi_agent_call"` - - `message: optional string` + - `id: optional string` - Details about the pending safety check. + The unique ID of this multi-agent call. - `agent: optional object { agent_name }` @@ -138756,139 +136755,127 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` - - The identifier of the actor that created the item. - - - `Reasoning object { id, summary, type, 4 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). + - `MultiAgentCallOutput object { action, call_id, output, 3 more }` - - `id: string` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - The unique identifier of the reasoning content. + The multi-agent action that produced this result. - - `summary: array of object { text, type }` + - `"spawn_agent"` - Reasoning summary content. + - `"interrupt_agent"` - - `text: string` + - `"list_agents"` - A summary of the reasoning output from the model so far. + - `"send_message"` - - `type: "summary_text"` + - `"followup_task"` - The type of the object. Always `summary_text`. + - `"wait_agent"` - - `"summary_text"` + - `call_id: string` - - `type: "reasoning"` + The unique ID of the multi-agent call. - The type of the object. Always `reasoning`. + - `output: array of object { text, type, annotations }` - - `"reasoning"` + Text output returned by the multi-agent action. - - `agent: optional object { agent_name }` + - `text: string` - The agent that produced this item. + The text content. - - `agent_name: string` + - `type: "output_text"` - The canonical name of the agent that produced this item. + The content type. Always `output_text`. - - `content: optional array of object { text, type }` + - `"output_text"` - Reasoning text content. + - `annotations: optional 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 }` - - `text: string` + Citations associated with the text content. - The reasoning text from the model. + - `FileCitation object { file_id, filename, index, type }` - - `type: "reasoning_text"` + - `file_id: string` - The type of the reasoning text. Always `reasoning_text`. + The ID of the file. - - `"reasoning_text"` + - `filename: string` - - `encrypted_content: optional string` + The filename of the file cited. - 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. + - `index: number` - - `status: optional "in_progress" or "completed" or "incomplete"` + The index of the file in the list of files. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `type: "file_citation"` - - `"in_progress"` + The citation type. Always `file_citation`. - - `"completed"` + - `"file_citation"` - - `"incomplete"` + - `URLCitation object { end_index, start_index, title, 2 more }` - - `Program object { id, call_id, code, 3 more }` + - `end_index: number` - - `id: string` + The index of the last character of the citation in the message. - The unique ID of the program item. + - `start_index: number` - - `call_id: string` + The index of the first character of the citation in the message. - The stable call ID of the program item. + - `title: string` - - `code: string` + The title of the cited resource. - The JavaScript source executed by programmatic tool calling. + - `type: "url_citation"` - - `fingerprint: string` + The citation type. Always `url_citation`. - Opaque program replay fingerprint that must be round-tripped. + - `"url_citation"` - - `type: "program"` + - `url: string` - The type of the item. Always `program`. + The URL of the cited resource. - - `"program"` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - - `agent: optional object { agent_name }` + - `container_id: string` - The agent that produced this item. + The ID of the container. - - `agent_name: string` + - `end_index: number` - The canonical name of the agent that produced this item. + The index of the last character of the citation in the message. - - `ProgramOutput object { id, call_id, result, 3 more }` + - `file_id: string` - - `id: string` + The ID of the container file. - The unique ID of the program output item. + - `filename: string` - - `call_id: string` + The filename of the container file cited. - The call ID of the program item. + - `start_index: number` - - `result: string` + The index of the first character of the citation in the message. - The result produced by the program item. + - `type: "container_file_citation"` - - `status: "completed" or "incomplete"` + The citation type. Always `container_file_citation`. - The terminal status of the program output item. + - `"container_file_citation"` - - `"completed"` + - `type: "multi_agent_call_output"` - - `"incomplete"` + The item type. Always `multi_agent_call_output`. - - `type: "program_output"` + - `"multi_agent_call_output"` - The type of the item. Always `program_output`. + - `id: optional string` - - `"program_output"` + The unique ID of this multi-agent call output. - `agent: optional object { agent_name }` @@ -138898,44 +136885,22 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `ToolSearchCall object { id, arguments, call_id, 5 more }` - - - `id: string` - - The unique ID of the tool search call item. + - `ToolSearchCall object { arguments, type, id, 4 more }` - `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"` + The arguments supplied to the tool search call. - `type: "tool_search_call"` - The type of the item. Always `tool_search_call`. + The item type. Always `tool_search_call`. - `"tool_search_call"` + - `id: optional string` + + The unique ID of this tool search call. + - `agent: optional object { agent_name }` The agent that produced this item. @@ -138944,21 +136909,11 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` - - The identifier of the actor that created the item. - - - `ToolSearchOutput object { id, call_id, execution, 5 more }` - - - `id: string` - - The unique ID of the tool search output item. - - - `call_id: string` + - `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. @@ -138966,9 +136921,9 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"client"` - - `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 tool search call. - `"in_progress"` @@ -138976,9 +136931,11 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` + - `ToolSearchOutput object { tools, type, id, 4 more }` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - The loaded tool definitions returned by tool search. + The loaded tool definitions returned by the tool search output. - `Function object { name, parameters, strict, 5 more }` @@ -140121,10 +138078,14 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "tool_search_output"` - The type of the item. Always `tool_search_output`. + The item type. Always `tool_search_output`. - `"tool_search_output"` + - `id: optional string` + + The unique ID of this tool search output. + - `agent: optional object { agent_name }` The agent that produced this item. @@ -140133,39 +138094,39 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` + - `call_id: optional string` - The identifier of the actor that created the item. + The unique ID of the tool search call generated by the model. - - `AdditionalTools object { id, role, tools, 2 more }` + - `execution: optional "server" or "client"` - - `id: string` + Whether tool search was executed by the server or by the client. - The unique ID of the additional tools item. + - `"server"` - - `role: "unknown" or "user" or "assistant" or 5 more` + - `"client"` - The role that provided the additional tools. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"unknown"` + The status of the tool search output. - - `"user"` + - `"in_progress"` - - `"assistant"` + - `"completed"` - - `"system"` + - `"incomplete"` - - `"critic"` + - `AdditionalTools object { role, tools, type, 2 more }` - - `"discriminator"` + - `role: "developer"` - - `"developer"` + The role that provided the additional tools. Only `developer` is supported. - - `"tool"` + - `"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 }` @@ -141132,35 +139093,1060 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `region: optional string` - Free text input for the region of the user, e.g. `California`. + 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: "additional_tools"` + + The item type. Always `additional_tools`. + + - `"additional_tools"` + + - `id: optional string` + + The unique ID of this additional tools item. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `Reasoning object { id, summary, type, 4 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 object { text, type }` + + 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"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `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, agent }` + + 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. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `ImageGenerationCall object { id, result, status, 2 more }` + + An image generation request made by the model. + + - `id: string` + + The unique ID of the image generation call. + + - `result: string` + + The generated image encoded in base64. + + - `status: "in_progress" or "completed" or "generating" or "failed"` + + The status of the image generation call. + + - `"in_progress"` + + - `"completed"` + + - `"generating"` + + - `"failed"` + + - `type: "image_generation_call"` + + The type of the image generation call. Always `image_generation_call`. + + - `"image_generation_call"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `CodeInterpreterCall object { id, code, container_id, 4 more }` + + A tool call to run code. + + - `id: string` + + The unique ID of the code interpreter tool call. + + - `code: string` + + The code to run, or null if not available. + + - `container_id: string` + + The ID of the container used to run the code. + + - `outputs: array of object { logs, type } or object { type, url }` + + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. + + - `Logs object { logs, type }` + + The logs output from the code interpreter. + + - `logs: string` + + The logs output from the code interpreter. + + - `type: "logs"` + + The type of the output. Always `logs`. + + - `"logs"` + + - `Image object { type, url }` + + The image output from the code interpreter. + + - `type: "image"` + + The type of the output. Always `image`. + + - `"image"` + + - `url: string` + + The URL of the image output from the code interpreter. + + - `status: "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"interpreting"` + + - `"failed"` + + - `type: "code_interpreter_call"` + + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `"code_interpreter_call"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `LocalShellCall object { id, action, call_id, 3 more }` + + A tool call to run a command on the local shell. + + - `id: string` + + The unique ID of the local shell call. + + - `action: object { command, env, type, 3 more }` + + Execute a shell command on the server. + + - `command: array of string` + + The command to run. + + - `env: map[string]` + + Environment variables to set for the command. + + - `type: "exec"` + + The type of the local shell action. Always `exec`. + + - `"exec"` + + - `timeout_ms: optional number` + + Optional timeout in milliseconds for the command. + + - `user: optional string` + + Optional user to run the command as. + + - `working_directory: optional string` + + Optional working directory to run the command in. + + - `call_id: string` + + The unique ID of the local shell tool call generated by the model. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the local shell call. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "local_shell_call"` + + The type of the local shell call. Always `local_shell_call`. + + - `"local_shell_call"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `LocalShellCallOutput object { id, output, type, 2 more }` + + The output of a local shell tool call. + + - `id: string` + + The unique ID of the local shell tool call generated by the model. + + - `output: string` + + A JSON string of the output of the local shell tool call. + + - `type: "local_shell_call_output"` + + The type of the local shell tool call output. Always `local_shell_call_output`. + + - `"local_shell_call_output"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `ShellCall object { action, call_id, type, 5 more }` + + A tool representing a request to execute one or more shell commands. + + - `action: object { commands, max_output_length, timeout_ms }` + + The shell commands and limits that describe how to run the tool call. + + - `commands: array of string` + + Ordered shell commands for the execution environment to run. + + - `max_output_length: optional number` + + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + + - `timeout_ms: optional number` + + Maximum wall-clock time in milliseconds to allow the shell commands to run. + + - `call_id: string` + + The unique ID of the shell tool call generated by the model. + + - `type: "shell_call"` + + The type of the item. Always `shell_call`. + + - `"shell_call"` + + - `id: optional string` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + + - `environment: optional BetaLocalEnvironment or BetaContainerReference` + + The environment to execute the shell commands in. + + - `BetaLocalEnvironment object { type, skills }` + + - `BetaContainerReference object { container_id, type }` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `ShellCallOutput object { call_id, output, type, 5 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 BetaResponseFunctionShellCallOutputContent` + + Captured chunks of stdout and stderr output, along with their associated outcomes. + + - `outcome: object { type } or object { exit_code, type }` + + The exit or timeout outcome associated with this shell call. + + - `Timeout object { type }` + + Indicates that the shell call exceeded its configured time limit. + + - `type: "timeout"` + + The outcome type. Always `timeout`. + + - `"timeout"` + + - `Exit object { exit_code, type }` + + Indicates that the shell commands finished and returned an exit code. + + - `exit_code: number` + + The exit code returned by the shell process. + + - `type: "exit"` + + The outcome type. Always `exit`. + + - `"exit"` + + - `stderr: string` + + Captured stderr output for the shell call. + + - `stdout: string` + + Captured stdout output for the shell call. + + - `type: "shell_call_output"` + + The type of the item. Always `shell_call_output`. + + - `"shell_call_output"` + + - `id: optional string` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + + - `max_output_length: optional number` + + The maximum number of UTF-8 characters captured for this shell call's combined output. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the shell call output. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `ApplyPatchCall object { call_id, operation, status, 4 more }` + + A tool call representing a request to create, delete, or update files using diff patches. + + - `call_id: string` + + The unique ID of the apply patch tool call generated by the model. + + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + + The specific create, delete, or update instruction for the apply_patch tool call. + + - `CreateFile object { diff, path, type }` + + Instruction for creating a new file via the apply_patch tool. + + - `diff: string` + + Unified diff content to apply when creating the file. + + - `path: string` + + Path of the file to create relative to the workspace root. + + - `type: "create_file"` + + The operation type. Always `create_file`. + + - `"create_file"` + + - `DeleteFile object { path, type }` + + Instruction for deleting an existing file via the apply_patch tool. + + - `path: string` + + Path of the file to delete relative to the workspace root. + + - `type: "delete_file"` + + The operation type. Always `delete_file`. + + - `"delete_file"` + + - `UpdateFile object { diff, path, type }` + + Instruction for updating an existing file via the apply_patch tool. + + - `diff: string` + + Unified diff content to apply to the existing file. + + - `path: string` + + Path of the file to update relative to the workspace root. + + - `type: "update_file"` + + The operation type. Always `update_file`. + + - `"update_file"` + + - `status: "in_progress" or "completed"` + + The status of the apply patch tool call. One of `in_progress` or `completed`. + + - `"in_progress"` + + - `"completed"` + + - `type: "apply_patch_call"` + + The type of the item. Always `apply_patch_call`. + + - `"apply_patch_call"` + + - `id: optional string` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + + - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` + + The streamed output emitted by an apply patch tool call. + + - `call_id: string` + + The unique ID of the apply patch tool call generated by the model. + + - `status: "completed" or "failed"` + + The status of the apply patch tool call output. One of `completed` or `failed`. + + - `"completed"` + + - `"failed"` + + - `type: "apply_patch_call_output"` + + The type of the item. Always `apply_patch_call_output`. + + - `"apply_patch_call_output"` + + - `id: optional string` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + + - `output: optional string` + + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + + - `McpListTools object { id, server_label, tools, 3 more }` + + A list of tools available on an MCP server. + + - `id: string` + + The unique ID of the list. + + - `server_label: string` + + The label of the MCP server. + + - `tools: array of object { input_schema, name, annotations, description }` + + The tools available on the server. + + - `input_schema: unknown` + + The JSON schema describing the tool's input. + + - `name: string` + + The name of the tool. + + - `annotations: optional unknown` + + Additional annotations about the tool. + + - `description: optional string` + + The description of the tool. + + - `type: "mcp_list_tools"` + + The type of the item. Always `mcp_list_tools`. + + - `"mcp_list_tools"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `error: optional string` + + Error message if the server could not list tools. + + - `McpApprovalRequest object { id, arguments, name, 3 more }` + + A request for human approval of a tool invocation. + + - `id: string` + + The unique ID of the approval request. + + - `arguments: string` + + A JSON string of arguments for the tool. + + - `name: string` + + The name of the tool to run. + + - `server_label: string` + + The label of the MCP server making the request. + + - `type: "mcp_approval_request"` + + The type of the item. Always `mcp_approval_request`. + + - `"mcp_approval_request"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` + + A response to an MCP approval request. + + - `approval_request_id: string` + + The ID of the approval request being answered. + + - `approve: boolean` + + Whether the request was approved. + + - `type: "mcp_approval_response"` + + The type of the item. Always `mcp_approval_response`. + + - `"mcp_approval_response"` + + - `id: optional string` + + The unique ID of the approval response + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `reason: optional string` + + Optional reason for the decision. + + - `McpCall object { id, arguments, name, 7 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"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `approval_request_id: optional string` + + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + + - `error: optional string` + + The error from the tool call, if any. + + - `output: optional string` + + The output from the tool call. + + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"calling"` + + - `"failed"` + + - `CustomToolCallOutput object { call_id, output, type, 3 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. + + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + + 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 BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + + Text, image, or file output of the custom tool call. + + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](/docs/guides/vision). + + - `BetaResponseInputFile 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. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + + - `CustomToolCall object { call_id, input, name, 5 more }` + + A call to a custom tool created by the model. + + - `call_id: string` + + An identifier used to map this custom tool call to a tool call output. + + - `input: string` + + The input for the custom tool call generated by the model. + + - `name: string` + + The name of the custom tool being called. + + - `type: "custom_tool_call"` + + The type of the custom tool call. Always `custom_tool_call`. + + - `"custom_tool_call"` + + - `id: optional string` + + The unique ID of the custom tool call in the OpenAI platform. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `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` - - `timezone: optional string` + The namespace of the custom tool being called. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `CompactionTrigger object { type, agent }` - - `ApplyPatch object { type, allowed_callers }` + Compacts the current context. Must be the final input item. - Allows the assistant to create, delete, or update files using unified diffs. + - `type: "compaction_trigger"` - - `type: "apply_patch"` + The type of the item. Always `compaction_trigger`. - The type of the tool. Always `apply_patch`. + - `"compaction_trigger"` - - `"apply_patch"` + - `agent: optional object { agent_name }` - - `allowed_callers: optional array of "direct" or "programmatic"` + The agent that produced this item. - The tool invocation context(s). + - `agent_name: string` - - `"direct"` + The canonical name of the agent that produced this item. - - `"programmatic"` + - `ItemReference object { id, agent, type }` - - `type: "additional_tools"` + An internal identifier for an item to reference. - The type of the item. Always `additional_tools`. + - `id: string` - - `"additional_tools"` + The ID of the item to reference. - `agent: optional object { agent_name }` @@ -141170,23 +140156,35 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `Compaction object { id, encrypted_content, type, 2 more }` + - `type: optional "item_reference"` - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + The type of item to reference. Always `item_reference`. + + - `"item_reference"` + + - `Program object { id, call_id, code, 3 more }` - `id: string` - The unique ID of the compaction item. + The unique ID of this program item. - - `encrypted_content: string` + - `call_id: string` - The encrypted content that was produced by compaction. + The stable call ID of the program item. - - `type: "compaction"` + - `code: string` - The type of the item. Always `compaction`. + The JavaScript source executed by programmatic tool calling. - - `"compaction"` + - `fingerprint: string` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: "program"` + + The item type. Always `program`. + + - `"program"` - `agent: optional object { agent_name }` @@ -141196,39 +140194,33 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` - - The identifier of the actor that created the item. + - `ProgramOutput object { id, call_id, result, 3 more }` - - `ImageGenerationCall object { id, result, status, 2 more }` + - `id: string` - An image generation request made by the model. + The unique ID of this program output item. - - `id: string` + - `call_id: string` - The unique ID of the image generation call. + The call ID of the program item. - `result: string` - The generated image encoded in base64. - - - `status: "in_progress" or "completed" or "generating" or "failed"` + The result produced by the program item. - The status of the image generation call. + - `status: "completed" or "incomplete"` - - `"in_progress"` + The terminal status of the program output. - `"completed"` - - `"generating"` - - - `"failed"` + - `"incomplete"` - - `type: "image_generation_call"` + - `type: "program_output"` - The type of the image generation call. Always `image_generation_call`. + The item type. Always `program_output`. - - `"image_generation_call"` + - `"program_output"` - `agent: optional object { agent_name }` @@ -141238,592 +140230,603 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `CodeInterpreterCall object { id, code, container_id, 4 more }` + - `response_id: string` - A tool call to run code. + The ID of the response that rejected the input. - - `id: string` + - `sequence_number: number` - The unique ID of the code interpreter tool call. + The sequence number for this event. - - `code: string` + - `type: "response.inject.failed"` - The code to run, or null if not available. + The event discriminator. Always `response.inject.failed`. - - `container_id: string` + - `"response.inject.failed"` - The ID of the container used to run the code. + - `stream_id: optional string` - - `outputs: array of object { logs, type } or object { type, url }` + The multiplexed WebSocket stream that emitted the event. This field is + present only when WebSocket multiplexing is enabled separately. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. +### Beta Response Input Audio - - `Logs object { logs, type }` +- `BetaResponseInputAudio object { input_audio, type }` - The logs output from the code interpreter. + An audio input to the model. - - `logs: string` + - `input_audio: object { data, format }` - The logs output from the code interpreter. + - `data: string` - - `type: "logs"` + Base64-encoded audio data. - The type of the output. Always `logs`. + - `format: "mp3" or "wav"` - - `"logs"` + The format of the audio data. Currently supported formats are `mp3` and + `wav`. - - `Image object { type, url }` + - `"mp3"` - The image output from the code interpreter. + - `"wav"` - - `type: "image"` + - `type: "input_audio"` - The type of the output. Always `image`. + The type of the input item. Always `input_audio`. - - `"image"` + - `"input_audio"` - - `url: string` +### Beta Response Input Content - The URL of the image output from the code interpreter. +- `BetaResponseInputContent = BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + A text input to the model. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `"in_progress"` + A text input to the model. - - `"completed"` + - `text: string` - - `"incomplete"` + The text input to the model. - - `"interpreting"` + - `type: "input_text"` - - `"failed"` + The type of the input item. Always `input_text`. - - `type: "code_interpreter_call"` + - `"input_text"` - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `prompt_cache_breakpoint: optional object { mode }` - - `"code_interpreter_call"` + 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. - - `agent: optional object { agent_name }` + - `mode: "explicit"` - The agent that produced this item. + The breakpoint mode. Always `explicit`. - - `agent_name: string` + - `"explicit"` - The canonical name of the agent that produced this item. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `LocalShellCall object { id, action, call_id, 3 more }` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - A tool call to run a command on the local shell. + - `detail: "low" or "high" or "auto" or "original"` - - `id: string` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The unique ID of the local shell call. + - `"low"` - - `action: object { command, env, type, 3 more }` + - `"high"` - Execute a shell command on the server. + - `"auto"` - - `command: array of string` + - `"original"` - The command to run. + - `type: "input_image"` - - `env: map[string]` + The type of the input item. Always `input_image`. - Environment variables to set for the command. + - `"input_image"` - - `type: "exec"` + - `file_id: optional string` - The type of the local shell action. Always `exec`. + The ID of the file to be sent to the model. - - `"exec"` + - `image_url: optional string` - - `timeout_ms: optional number` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - Optional timeout in milliseconds for the command. + - `prompt_cache_breakpoint: optional object { mode }` - - `user: 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. - Optional user to run the command as. + - `mode: "explicit"` - - `working_directory: optional string` + The breakpoint mode. Always `explicit`. - Optional working directory to run the command in. + - `"explicit"` - - `call_id: string` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - The unique ID of the local shell tool call generated by the model. + A file input to the model. - - `status: "in_progress" or "completed" or "incomplete"` + - `type: "input_file"` - The status of the local shell call. + The type of the input item. Always `input_file`. - - `"in_progress"` + - `"input_file"` - - `"completed"` + - `detail: optional "auto" or "low" or "high"` - - `"incomplete"` + 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: "local_shell_call"` + - `"auto"` - The type of the local shell call. Always `local_shell_call`. + - `"low"` - - `"local_shell_call"` + - `"high"` - - `agent: optional object { agent_name }` + - `file_data: optional string` - The agent that produced this item. + The content of the file to be sent to the model. - - `agent_name: string` + - `file_id: optional string` - The canonical name of the agent that produced this item. + The ID of the file to be sent to the model. - - `LocalShellCallOutput object { id, output, type, 2 more }` + - `file_url: optional string` - The output of a local shell tool call. + The URL of the file to be sent to the model. - - `id: string` + - `filename: optional string` - The unique ID of the local shell tool call generated by the model. + The name of the file to be sent to the model. - - `output: string` + - `prompt_cache_breakpoint: optional object { mode }` - A JSON string of the output of the local shell tool call. + 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: "local_shell_call_output"` + - `mode: "explicit"` - The type of the local shell tool call output. Always `local_shell_call_output`. + The breakpoint mode. Always `explicit`. - - `"local_shell_call_output"` + - `"explicit"` - - `agent: optional object { agent_name }` +### Beta Response Input File - The agent that produced this item. +- `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `agent_name: string` + A file input to the model. - The canonical name of the agent that produced this item. + - `type: "input_file"` - - `status: optional "in_progress" or "completed" or "incomplete"` + The type of the input item. Always `input_file`. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `"input_file"` - - `"in_progress"` + - `detail: optional "auto" or "low" or "high"` - - `"completed"` + 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`. - - `"incomplete"` + - `"auto"` - - `ShellCall object { id, action, call_id, 6 more }` + - `"low"` - A tool call that executes one or more shell commands in a managed environment. + - `"high"` - - `id: string` + - `file_data: optional string` - The unique ID of the shell tool call. Populated when this item is returned via API. + The content of the file to be sent to the model. - - `action: object { commands, max_output_length, timeout_ms }` + - `file_id: optional string` - The shell commands and limits that describe how to run the tool call. + The ID of the file to be sent to the model. - - `commands: array of string` + - `file_url: optional string` - - `max_output_length: number` + The URL of the file to be sent to the model. - Optional maximum number of characters to return from each command. + - `filename: optional string` - - `timeout_ms: number` + The name of the file to be sent to the model. - Optional timeout in milliseconds for the commands. + - `prompt_cache_breakpoint: optional object { mode }` - - `call_id: 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 shell tool call generated by the model. + - `mode: "explicit"` - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + The breakpoint mode. Always `explicit`. - Represents the use of a local environment to perform shell actions. + - `"explicit"` - - `BetaResponseLocalEnvironment object { type }` +### Beta Response Input File Content - Represents the use of a local environment to perform shell actions. +- `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` - - `type: "local"` + A file input to the model. - The environment type. Always `local`. + - `type: "input_file"` - - `"local"` + The type of the input item. Always `input_file`. - - `BetaResponseContainerReference object { container_id, type }` + - `"input_file"` - Represents a container created with /v1/containers. + - `detail: optional "auto" or "low" or "high"` - - `container_id: string` + 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: "container_reference"` + - `"auto"` - The environment type. Always `container_reference`. + - `"low"` - - `"container_reference"` + - `"high"` - - `status: "in_progress" or "completed" or "incomplete"` + - `file_data: optional string` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + The base64-encoded data of the file to be sent to the model. - - `"in_progress"` + - `file_id: optional string` - - `"completed"` + The ID of the file to be sent to the model. - - `"incomplete"` + - `file_url: optional string` - - `type: "shell_call"` + The URL of the file to be sent to the model. - The type of the item. Always `shell_call`. + - `filename: optional string` - - `"shell_call"` + The name of the file to be sent to the model. - - `agent: optional object { agent_name }` + - `prompt_cache_breakpoint: optional object { mode }` - The agent that produced this item. + 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. - - `agent_name: string` + - `mode: "explicit"` - The canonical name of the agent that produced this item. + The breakpoint mode. Always `explicit`. - - `caller: optional object { type } or object { caller_id, type }` + - `"explicit"` - The execution context that produced this tool call. +### Beta Response Input Image - - `Direct object { type }` +- `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `type: "direct"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"direct"` + - `detail: "low" or "high" or "auto" or "original"` - - `Program object { caller_id, type }` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `caller_id: string` + - `"low"` - The call ID of the program item that produced this tool call. + - `"high"` - - `type: "program"` + - `"auto"` - - `"program"` + - `"original"` - - `created_by: optional string` + - `type: "input_image"` - The ID of the entity that created this tool call. + The type of the input item. Always `input_image`. - - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` + - `"input_image"` - The output of a shell tool call that was emitted. + - `file_id: optional string` - - `id: string` + The ID of the file to be sent to the model. - The unique ID of the shell call output. Populated when this item is returned via API. + - `image_url: optional string` - - `call_id: 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 unique ID of the shell tool call generated by the model. + - `prompt_cache_breakpoint: optional object { mode }` - - `max_output_length: number` + 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 maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `mode: "explicit"` - - `output: array of object { outcome, stderr, stdout, created_by }` + The breakpoint mode. Always `explicit`. - An array of shell call output contents + - `"explicit"` - - `outcome: object { type } or object { exit_code, type }` +### Beta Response Input Image Content - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. +- `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - - `Timeout object { type }` + An image input to the model. Learn about [image inputs](/docs/guides/vision) - Indicates that the shell call exceeded its configured time limit. + - `type: "input_image"` - - `type: "timeout"` + The type of the input item. Always `input_image`. - The outcome type. Always `timeout`. + - `"input_image"` - - `"timeout"` + - `detail: optional "low" or "high" or "auto" or "original"` - - `Exit object { exit_code, type }` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - Indicates that the shell commands finished and returned an exit code. + - `"low"` - - `exit_code: number` + - `"high"` - Exit code from the shell process. + - `"auto"` - - `type: "exit"` + - `"original"` - The outcome type. Always `exit`. + - `file_id: optional string` - - `"exit"` + The ID of the file to be sent to the model. - - `stderr: string` + - `image_url: optional string` - The standard error output that was captured. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `stdout: string` + - `prompt_cache_breakpoint: optional object { mode }` - The standard output that was captured. + 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. - - `created_by: optional string` + - `mode: "explicit"` - The identifier of the actor that created the item. + The breakpoint mode. Always `explicit`. - - `status: "in_progress" or "completed" or "incomplete"` + - `"explicit"` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. +### Beta Response Input Message Content List - - `"in_progress"` +- `BetaResponseInputMessageContentList = array of BetaResponseInputContent` - - `"completed"` + A list of one or many input items to the model, containing different content + types. - - `"incomplete"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `type: "shell_call_output"` + A text input to the model. - The type of the shell call output. Always `shell_call_output`. + - `text: string` - - `"shell_call_output"` + The text input to the model. - - `agent: optional object { agent_name }` + - `type: "input_text"` - The agent that produced this item. + The type of the input item. Always `input_text`. - - `agent_name: string` + - `"input_text"` - The canonical name of the agent that produced this item. + - `prompt_cache_breakpoint: optional object { mode }` - - `caller: optional object { type } or object { caller_id, 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. - The execution context that produced this tool call. + - `mode: "explicit"` - - `Direct object { type }` + The breakpoint mode. Always `explicit`. - - `type: "direct"` + - `"explicit"` - - `"direct"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `Program object { caller_id, type }` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `caller_id: string` + - `detail: "low" or "high" or "auto" or "original"` - The call ID of the program item that produced this tool call. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `type: "program"` + - `"low"` - - `"program"` + - `"high"` - - `created_by: optional string` + - `"auto"` - The identifier of the actor that created the item. + - `"original"` - - `ApplyPatchCall object { id, call_id, operation, 5 more }` + - `type: "input_image"` - A tool call that applies file diffs by creating, deleting, or updating files. + The type of the input item. Always `input_image`. - - `id: string` + - `"input_image"` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `file_id: optional string` - - `call_id: string` + The ID of the file to be sent to the model. - The unique ID of the apply patch tool call generated by the model. + - `image_url: optional string` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - One of the create_file, delete_file, or update_file operations applied via apply_patch. + - `prompt_cache_breakpoint: optional object { mode }` - - `CreateFile object { diff, path, 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. - Instruction describing how to create a file via the apply_patch tool. + - `mode: "explicit"` - - `diff: string` + The breakpoint mode. Always `explicit`. - Diff to apply. + - `"explicit"` - - `path: string` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - Path of the file to create. + A file input to the model. - - `type: "create_file"` + - `type: "input_file"` - Create a new file with the provided diff. + The type of the input item. Always `input_file`. - - `"create_file"` + - `"input_file"` - - `DeleteFile object { path, type }` + - `detail: optional "auto" or "low" or "high"` - Instruction describing how to delete a file via the apply_patch 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`. - - `path: string` + - `"auto"` - Path of the file to delete. + - `"low"` - - `type: "delete_file"` + - `"high"` - Delete the specified file. + - `file_data: optional string` - - `"delete_file"` + The content of the file to be sent to the model. - - `UpdateFile object { diff, path, type }` + - `file_id: optional string` - Instruction describing how to update a file via the apply_patch tool. + The ID of the file to be sent to the model. - - `diff: string` + - `file_url: optional string` - Diff to apply. + The URL of the file to be sent to the model. - - `path: string` + - `filename: optional string` - Path of the file to update. + The name of the file to be sent to the model. - - `type: "update_file"` + - `prompt_cache_breakpoint: optional object { mode }` - Update an existing file with the provided diff. + 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. - - `"update_file"` + - `mode: "explicit"` - - `status: "in_progress" or "completed"` + The breakpoint mode. Always `explicit`. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `"explicit"` - - `"in_progress"` +### Beta Response Input Message Item - - `"completed"` +- `BetaResponseInputMessageItem object { id, content, role, 3 more }` - - `type: "apply_patch_call"` + - `id: string` - The type of the item. Always `apply_patch_call`. + The unique ID of the message input. - - `"apply_patch_call"` + - `content: BetaResponseInputMessageContentList` - - `agent: optional object { agent_name }` + A list of one or many input items to the model, containing different content + types. - The agent that produced this item. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `agent_name: string` + A text input to the model. - The canonical name of the agent that produced this item. + - `text: string` - - `caller: optional object { type } or object { caller_id, type }` + The text input to the model. - The execution context that produced this tool call. + - `type: "input_text"` - - `Direct object { type }` + The type of the input item. Always `input_text`. - - `type: "direct"` + - `"input_text"` - - `"direct"` + - `prompt_cache_breakpoint: optional object { mode }` - - `Program object { caller_id, 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. - - `caller_id: string` + - `mode: "explicit"` - The call ID of the program item that produced this tool call. + The breakpoint mode. Always `explicit`. - - `type: "program"` + - `"explicit"` - - `"program"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `created_by: optional string` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - The ID of the entity that created this tool call. + - `detail: "low" or "high" or "auto" or "original"` - - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The output emitted by an apply patch tool call. + - `"low"` - - `id: string` + - `"high"` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `"auto"` - - `call_id: string` + - `"original"` - The unique ID of the apply patch tool call generated by the model. + - `type: "input_image"` - - `status: "completed" or "failed"` + The type of the input item. Always `input_image`. - The status of the apply patch tool call output. One of `completed` or `failed`. + - `"input_image"` - - `"completed"` + - `file_id: optional string` - - `"failed"` + The ID of the file to be sent to the model. - - `type: "apply_patch_call_output"` + - `image_url: optional string` - The type of the item. Always `apply_patch_call_output`. + 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_output"` + - `prompt_cache_breakpoint: optional object { mode }` - - `agent: optional object { agent_name }` + 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 agent that produced this item. + - `mode: "explicit"` - - `agent_name: string` + The breakpoint mode. Always `explicit`. - The canonical name of the agent that produced this item. + - `"explicit"` - - `caller: optional object { type } or object { caller_id, type }` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - The execution context that produced this tool call. + A file input to the model. - - `Direct object { type }` + - `type: "input_file"` - - `type: "direct"` + The type of the input item. Always `input_file`. - - `"direct"` + - `"input_file"` - - `Program object { caller_id, type }` + - `detail: optional "auto" or "low" or "high"` - - `caller_id: string` + 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 call ID of the program item that produced this tool call. + - `"auto"` - - `type: "program"` + - `"low"` - - `"program"` + - `"high"` - - `created_by: optional string` + - `file_data: optional string` - The ID of the entity that created this tool call output. + The content of the file to be sent to the model. - - `output: optional string` + - `file_id: optional string` - Optional textual output returned by the apply patch tool. + The ID of the file to be sent to the model. - - `McpCall object { id, arguments, name, 7 more }` + - `file_url: optional string` - An invocation of a tool on an MCP server. + The URL of the file to be sent to the model. - - `id: string` + - `filename: optional string` - The unique ID of the tool call. + The name of the file to be sent to the model. - - `arguments: string` + - `prompt_cache_breakpoint: optional object { mode }` - A JSON string of the arguments passed to the tool. + 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. - - `name: string` + - `mode: "explicit"` - The name of the tool that was run. + The breakpoint mode. Always `explicit`. - - `server_label: string` + - `"explicit"` - The label of the MCP server running the tool. + - `role: "user" or "system" or "developer"` - - `type: "mcp_call"` + The role of the message input. One of `user`, `system`, or `developer`. - The type of the item. Always `mcp_call`. + - `"user"` - - `"mcp_call"` + - `"system"` + + - `"developer"` + + - `type: "message"` + + The type of the message input. Always set to `message`. + + - `"message"` - `agent: optional object { agent_name }` @@ -141833,310 +140836,336 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `approval_request_id: optional string` + - `status: optional "in_progress" or "completed" or "incomplete"` - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `error: optional string` + - `"in_progress"` - The error from the tool call, if any. + - `"completed"` - - `output: optional string` + - `"incomplete"` - The output from the tool call. +### Beta Response Input Text - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` +- `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + A text input to the model. - - `"in_progress"` + - `text: string` - - `"completed"` + The text input to the model. - - `"incomplete"` + - `type: "input_text"` - - `"calling"` + The type of the input item. Always `input_text`. - - `"failed"` + - `"input_text"` - - `McpListTools object { id, server_label, tools, 3 more }` + - `prompt_cache_breakpoint: optional object { mode }` - A list of tools available on an MCP server. + 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. - - `id: string` + - `mode: "explicit"` - The unique ID of the list. + The breakpoint mode. Always `explicit`. - - `server_label: string` + - `"explicit"` - The label of the MCP server. +### Beta Response Input Text Content - - `tools: array of object { input_schema, name, annotations, description }` +- `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - The tools available on the server. + A text input to the model. - - `input_schema: unknown` + - `text: string` - The JSON schema describing the tool's input. + The text input to the model. - - `name: string` + - `type: "input_text"` - The name of the tool. + The type of the input item. Always `input_text`. - - `annotations: optional unknown` + - `"input_text"` - Additional annotations about the tool. + - `prompt_cache_breakpoint: optional object { mode }` - - `description: 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 description of the tool. + - `mode: "explicit"` - - `type: "mcp_list_tools"` + The breakpoint mode. Always `explicit`. - The type of the item. Always `mcp_list_tools`. + - `"explicit"` - - `"mcp_list_tools"` +### Beta Response Local Environment - - `agent: optional object { agent_name }` +- `BetaResponseLocalEnvironment object { type }` - The agent that produced this item. + Represents the use of a local environment to perform shell actions. - - `agent_name: string` + - `type: "local"` - The canonical name of the agent that produced this item. + The environment type. Always `local`. - - `error: optional string` + - `"local"` - Error message if the server could not list tools. +### Beta Response Mcp Call Arguments Delta Event - - `McpApprovalRequest object { id, arguments, name, 3 more }` +- `BetaResponseMcpCallArgumentsDeltaEvent object { delta, item_id, output_index, 3 more }` - A request for human approval of a tool invocation. + Emitted when there is a delta (partial update) to the arguments of an MCP tool call. - - `id: string` + - `delta: string` - The unique ID of the approval request. + A JSON string containing the partial update to the arguments for the MCP tool call. - - `arguments: string` + - `item_id: string` - A JSON string of arguments for the tool. + The unique identifier of the MCP tool call item being processed. - - `name: string` + - `output_index: number` - The name of the tool to run. + The index of the output item in the response's output array. - - `server_label: string` + - `sequence_number: number` - The label of the MCP server making the request. + The sequence number of this event. - - `type: "mcp_approval_request"` + - `type: "response.mcp_call_arguments.delta"` - The type of the item. Always `mcp_approval_request`. + The type of the event. Always 'response.mcp_call_arguments.delta'. - - `"mcp_approval_request"` + - `"response.mcp_call_arguments.delta"` - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` +### Beta Response Mcp Call Arguments Done Event - A response to an MCP approval request. +- `BetaResponseMcpCallArgumentsDoneEvent object { arguments, item_id, output_index, 3 more }` - - `id: string` + Emitted when the arguments for an MCP tool call are finalized. - The unique ID of the approval response + - `arguments: string` - - `approval_request_id: string` + A JSON string containing the finalized arguments for the MCP tool call. - The ID of the approval request being answered. + - `item_id: string` - - `approve: boolean` + The unique identifier of the MCP tool call item being processed. - Whether the request was approved. + - `output_index: number` - - `type: "mcp_approval_response"` + The index of the output item in the response's output array. - The type of the item. Always `mcp_approval_response`. + - `sequence_number: number` - - `"mcp_approval_response"` + The sequence number of this event. - - `agent: optional object { agent_name }` + - `type: "response.mcp_call_arguments.done"` - The agent that produced this item. + The type of the event. Always 'response.mcp_call_arguments.done'. - - `agent_name: string` + - `"response.mcp_call_arguments.done"` - The canonical name of the agent that produced this item. + - `agent: optional object { agent_name }` - - `reason: optional string` + The agent that owns this multi-agent streaming event. - Optional reason for the decision. + - `agent_name: string` - - `CustomToolCall object { call_id, input, name, 5 more }` + The canonical name of the agent that produced this item. - A call to a custom tool created by the model. +### Beta Response Mcp Call Completed Event - - `call_id: string` +- `BetaResponseMcpCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - An identifier used to map this custom tool call to a tool call output. + Emitted when an MCP tool call has completed successfully. - - `input: string` + - `item_id: string` - The input for the custom tool call generated by the model. + The ID of the MCP tool call item that completed. - - `name: string` + - `output_index: number` - The name of the custom tool being called. + The index of the output item that completed. - - `type: "custom_tool_call"` + - `sequence_number: number` - The type of the custom tool call. Always `custom_tool_call`. + The sequence number of this event. - - `"custom_tool_call"` + - `type: "response.mcp_call.completed"` - - `id: optional string` + The type of the event. Always 'response.mcp_call.completed'. - The unique ID of the custom tool call in the OpenAI platform. + - `"response.mcp_call.completed"` - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` +### Beta Response Mcp Call Failed Event - The execution context that produced this tool call. +- `BetaResponseMcpCallFailedEvent object { item_id, output_index, sequence_number, 2 more }` - - `Direct object { type }` + Emitted when an MCP tool call has failed. - - `type: "direct"` + - `item_id: string` - - `"direct"` + The ID of the MCP tool call item that failed. - - `Program object { caller_id, type }` + - `output_index: number` - - `caller_id: string` + The index of the output item that failed. - The call ID of the program item that produced this tool call. + - `sequence_number: number` - - `type: "program"` + The sequence number of this event. - - `"program"` + - `type: "response.mcp_call.failed"` - - `namespace: optional string` + The type of the event. Always 'response.mcp_call.failed'. - The namespace of the custom tool being called. + - `"response.mcp_call.failed"` - - `CustomToolCallOutput object { id, call_id, output, 5 more }` + - `agent: optional object { agent_name }` - - `id: string` + The agent that owns this multi-agent streaming event. - The unique ID of the custom tool call output item. + - `agent_name: string` - - `call_id: string` + The canonical name of the agent that produced this item. - The call ID, used to map this custom tool call output to a custom tool call. +### Beta Response Mcp Call In Progress Event - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` +- `BetaResponseMcpCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + Emitted when an MCP tool call is in progress. - - `StringOutput = string` + - `item_id: string` - A string of the output of the custom tool call. + The unique identifier of the MCP tool call item being processed. - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `output_index: number` - Text, image, or file output of the custom tool call. + The index of the output item in the response's output array. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `sequence_number: number` - A text input to the model. + The sequence number of this event. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `type: "response.mcp_call.in_progress"` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + The type of the event. Always 'response.mcp_call.in_progress'. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `"response.mcp_call.in_progress"` - A file input to the model. + - `agent: optional object { agent_name }` - - `status: "in_progress" or "completed" or "incomplete"` + The agent that owns this multi-agent streaming event. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `agent_name: string` - - `"in_progress"` + The canonical name of the agent that produced this item. - - `"completed"` +### Beta Response Mcp List Tools Completed Event - - `"incomplete"` +- `BetaResponseMcpListToolsCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - - `type: "custom_tool_call_output"` + Emitted when the list of available MCP tools has been successfully retrieved. - The type of the custom tool call output. Always `custom_tool_call_output`. + - `item_id: string` - - `"custom_tool_call_output"` + The ID of the MCP tool call item that produced this output. + + - `output_index: number` + + The index of the output item that was processed. + + - `sequence_number: number` + + The sequence number of this event. + + - `type: "response.mcp_list_tools.completed"` + + The type of the event. Always 'response.mcp_list_tools.completed'. + + - `"response.mcp_list_tools.completed"` - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` +### Beta Response Mcp List Tools Failed Event - The execution context that produced this tool call. +- `BetaResponseMcpListToolsFailedEvent object { item_id, output_index, sequence_number, 2 more }` - - `Direct object { type }` + Emitted when the attempt to list available MCP tools has failed. - - `type: "direct"` + - `item_id: string` - The caller type. Always `direct`. + The ID of the MCP tool call item that failed. - - `"direct"` + - `output_index: number` - - `Program object { caller_id, type }` + The index of the output item that failed. - - `caller_id: string` + - `sequence_number: number` - The call ID of the program item that produced this tool call. + The sequence number of this event. - - `type: "program"` + - `type: "response.mcp_list_tools.failed"` - The caller type. Always `program`. + The type of the event. Always 'response.mcp_list_tools.failed'. - - `"program"` + - `"response.mcp_list_tools.failed"` - - `created_by: optional string` + - `agent: optional object { agent_name }` - The identifier of the actor that created the item. + The agent that owns this multi-agent streaming event. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + +### Beta Response Mcp List Tools In Progress Event + +- `BetaResponseMcpListToolsInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + + Emitted when the system is in the process of retrieving the list of available MCP tools. + + - `item_id: string` + + The ID of the MCP tool call item that is being processed. - `output_index: number` - The index of the output item that was added. + The index of the output item that is being processed. - `sequence_number: number` The sequence number of this event. - - `type: "response.output_item.added"` + - `type: "response.mcp_list_tools.in_progress"` - The type of the event. Always `response.output_item.added`. + The type of the event. Always 'response.mcp_list_tools.in_progress'. - - `"response.output_item.added"` + - `"response.mcp_list_tools.in_progress"` - `agent: optional object { agent_name }` @@ -142146,15 +141175,31 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. -### Beta Response Output Item Done Event +### Beta Response Output Audio -- `BetaResponseOutputItemDoneEvent object { item, output_index, sequence_number, 2 more }` +- `BetaResponseOutputAudio object { data, transcript, type }` - Emitted when an output item is marked done. + An audio output from the model. - - `item: BetaResponseOutputItem` + - `data: string` - The output item that was marked done. + Base64-encoded audio data from the model. + + - `transcript: string` + + The transcript of the audio data from the model. + + - `type: "output_audio"` + + The type of the output audio. Always `output_audio`. + + - `"output_audio"` + +### Beta Response Output Item + +- `BetaResponseOutputItem = BetaResponseOutputMessage or object { id, queries, status, 3 more } or object { arguments, call_id, name, 6 more } or 28 more` + + An output message from the model. - `BetaResponseOutputMessage object { id, content, role, 4 more }` @@ -146253,1371 +145298,528 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"direct"` - - `Program object { caller_id, type }` - - - `caller_id: string` - - The call ID of the program item that produced this tool call. - - - `type: "program"` - - - `"program"` - - - `created_by: optional string` - - The identifier of the actor that created the item. - - - `ApplyPatchCall object { id, call_id, operation, 5 more }` - - A tool call that applies file diffs by creating, deleting, or updating files. - - - `id: string` - - The unique ID of the apply patch tool call. Populated when this item is returned via API. - - - `call_id: string` - - The unique ID of the apply patch tool call generated by the model. - - - `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. - - - `CreateFile object { diff, path, type }` - - Instruction describing how to create a file via the apply_patch tool. - - - `diff: string` - - Diff to apply. - - - `path: string` - - Path of the file to create. - - - `type: "create_file"` - - Create a new file with the provided diff. - - - `"create_file"` - - - `DeleteFile object { path, type }` - - Instruction describing how to delete a file via the apply_patch tool. - - - `path: string` - - Path of the file to delete. - - - `type: "delete_file"` - - Delete the specified file. - - - `"delete_file"` - - - `UpdateFile object { diff, path, type }` - - Instruction describing how to update a file via the apply_patch tool. - - - `diff: string` - - Diff to apply. - - - `path: string` - - Path of the file to update. - - - `type: "update_file"` - - Update an existing file with the provided diff. - - - `"update_file"` - - - `status: "in_progress" or "completed"` - - The status of the apply patch tool call. One of `in_progress` or `completed`. - - - `"in_progress"` - - - `"completed"` - - - `type: "apply_patch_call"` - - The type of the item. Always `apply_patch_call`. - - - `"apply_patch_call"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `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, 5 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"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `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, 7 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"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `approval_request_id: optional string` - - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - - `error: optional string` - - The error from the tool call, if any. - - - `output: optional string` - - The output from the tool call. - - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `"calling"` - - - `"failed"` - - - `McpListTools object { id, server_label, tools, 3 more }` - - A list of tools available on an MCP server. - - - `id: string` - - The unique ID of the list. - - - `server_label: string` - - The label of the MCP server. - - - `tools: array of object { input_schema, name, annotations, description }` - - The tools available on the server. - - - `input_schema: unknown` - - The JSON schema describing the tool's input. - - - `name: string` - - The name of the tool. - - - `annotations: optional unknown` - - Additional annotations about the tool. - - - `description: optional string` - - The description of the tool. - - - `type: "mcp_list_tools"` - - The type of the item. Always `mcp_list_tools`. - - - `"mcp_list_tools"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `error: optional string` - - Error message if the server could not list tools. - - - `McpApprovalRequest object { id, arguments, name, 3 more }` - - A request for human approval of a tool invocation. - - - `id: string` - - The unique ID of the approval request. - - - `arguments: string` - - A JSON string of arguments for the tool. - - - `name: string` - - The name of the tool to run. - - - `server_label: string` - - The label of the MCP server making the request. - - - `type: "mcp_approval_request"` - - The type of the item. Always `mcp_approval_request`. - - - `"mcp_approval_request"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `McpApprovalResponse object { id, approval_request_id, approve, 3 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. - - - `approve: boolean` - - Whether the request was approved. - - - `type: "mcp_approval_response"` - - The type of the item. Always `mcp_approval_response`. - - - `"mcp_approval_response"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `reason: optional string` - - Optional reason for the decision. - - - `CustomToolCall object { call_id, input, name, 5 more }` - - A call to a custom tool created by the model. - - - `call_id: string` - - An identifier used to map this custom tool call to a tool call output. - - - `input: string` - - The input for the custom tool call generated by the model. - - - `name: string` - - The name of the custom tool being called. - - - `type: "custom_tool_call"` - - The type of the custom tool call. Always `custom_tool_call`. - - - `"custom_tool_call"` - - - `id: optional string` - - The unique ID of the custom tool call in the OpenAI platform. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `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, 5 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 BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - 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 BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - Text, image, or file output of the custom tool call. - - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](/docs/guides/vision). - - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - A file input to the model. - - - `status: "in_progress" or "completed" or "incomplete"` - - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `type: "custom_tool_call_output"` - - The type of the custom tool call output. Always `custom_tool_call_output`. - - - `"custom_tool_call_output"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. - - - `Direct object { type }` - - - `type: "direct"` - - The caller type. Always `direct`. - - - `"direct"` - - - `Program object { caller_id, type }` - - - `caller_id: string` - - The call ID of the program item that produced this tool call. - - - `type: "program"` - - The caller type. Always `program`. - - - `"program"` - - - `created_by: optional string` - - The identifier of the actor that created the item. - - - `output_index: number` - - The index of the output item that was marked done. - - - `sequence_number: number` - - The sequence number of this event. - - - `type: "response.output_item.done"` - - The type of the event. Always `response.output_item.done`. - - - `"response.output_item.done"` - - - `agent: optional object { agent_name }` - - The agent that owns this multi-agent streaming event. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - -### Beta Response Output Message - -- `BetaResponseOutputMessage object { id, content, role, 4 more }` - - An output message from the model. - - - `id: string` - - The unique ID of the output message. - - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - - The content of the output message. - - - `BetaResponseOutputText 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"` - - - `BetaResponseOutputRefusal 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"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `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"` - -### Beta Response Output Refusal - -- `BetaResponseOutputRefusal 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"` - -### Beta Response Output Text - -- `BetaResponseOutputText 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` + - `Program object { caller_id, type }` - The filename of the container file cited. + - `caller_id: string` - - `start_index: number` + The call ID of the program item that produced this tool call. - The index of the first character of the container file citation in the message. + - `type: "program"` - - `type: "container_file_citation"` + - `"program"` - The type of the container file citation. Always `container_file_citation`. + - `created_by: optional string` - - `"container_file_citation"` + The identifier of the actor that created the item. - - `FilePath object { file_id, index, type }` + - `ApplyPatchCall object { id, call_id, operation, 5 more }` - A path to a file. + A tool call that applies file diffs by creating, deleting, or updating files. - - `file_id: string` + - `id: string` - The ID of the file. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `index: number` + - `call_id: string` - The index of the file in the list of files. + The unique ID of the apply patch tool call generated by the model. - - `type: "file_path"` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - The type of the file path. Always `file_path`. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `"file_path"` + - `CreateFile object { diff, path, type }` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + Instruction describing how to create a file via the apply_patch tool. - - `token: string` + - `diff: string` - - `bytes: array of number` + Diff to apply. - - `logprob: number` + - `path: string` - - `top_logprobs: array of object { token, bytes, logprob }` + Path of the file to create. - - `token: string` + - `type: "create_file"` - - `bytes: array of number` + Create a new file with the provided diff. - - `logprob: number` + - `"create_file"` - - `text: string` + - `DeleteFile object { path, type }` - The text output from the model. + Instruction describing how to delete a file via the apply_patch tool. - - `type: "output_text"` + - `path: string` - The type of the output text. Always `output_text`. + Path of the file to delete. - - `"output_text"` + - `type: "delete_file"` -### Beta Response Output Text Annotation Added Event + Delete the specified file. -- `BetaResponseOutputTextAnnotationAddedEvent object { annotation, annotation_index, content_index, 5 more }` + - `"delete_file"` - Emitted when an annotation is added to output text content. + - `UpdateFile object { diff, path, type }` - - `annotation: unknown` + Instruction describing how to update a file via the apply_patch tool. - The annotation object being added. (See annotation schema for details.) + - `diff: string` - - `annotation_index: number` + Diff to apply. - The index of the annotation within the content part. + - `path: string` - - `content_index: number` + Path of the file to update. - The index of the content part within the output item. + - `type: "update_file"` - - `item_id: string` + Update an existing file with the provided diff. - The unique identifier of the item to which the annotation is being added. + - `"update_file"` - - `output_index: number` + - `status: "in_progress" or "completed"` - The index of the output item in the response's output array. + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `sequence_number: number` + - `"in_progress"` - The sequence number of this event. + - `"completed"` - - `type: "response.output_text.annotation.added"` + - `type: "apply_patch_call"` - The type of the event. Always 'response.output_text.annotation.added'. + The type of the item. Always `apply_patch_call`. - - `"response.output_text.annotation.added"` + - `"apply_patch_call"` - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. -### Beta Response Prompt - -- `BetaResponsePrompt object { id, variables, version }` + - `caller: optional object { type } or object { caller_id, type }` - Reference to a prompt template and its variables. - [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). + The execution context that produced this tool call. - - `id: string` + - `Direct object { type }` - The unique identifier of the prompt template to use. + - `type: "direct"` - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + - `"direct"` - 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. + - `Program object { caller_id, type }` - - `string` + - `caller_id: string` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + The call ID of the program item that produced this tool call. - A text input to the model. + - `type: "program"` - - `text: string` + - `"program"` - The text input to the model. + - `created_by: optional string` - - `type: "input_text"` + The ID of the entity that created this tool call. - The type of the input item. Always `input_text`. + - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` - - `"input_text"` + The output emitted by an apply patch tool call. - - `prompt_cache_breakpoint: optional object { mode }` + - `id: 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 output. Populated when this item is returned via API. - - `mode: "explicit"` + - `call_id: string` - The breakpoint mode. Always `explicit`. + The unique ID of the apply patch tool call generated by the model. - - `"explicit"` + - `status: "completed" or "failed"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + The status of the apply patch tool call output. One of `completed` or `failed`. - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `"completed"` - - `detail: "low" or "high" or "auto" or "original"` + - `"failed"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `type: "apply_patch_call_output"` - - `"low"` + The type of the item. Always `apply_patch_call_output`. - - `"high"` + - `"apply_patch_call_output"` - - `"auto"` + - `agent: optional object { agent_name }` - - `"original"` + The agent that produced this item. - - `type: "input_image"` + - `agent_name: string` - The type of the input item. Always `input_image`. + The canonical name of the agent that produced this item. - - `"input_image"` + - `caller: optional object { type } or object { caller_id, type }` - - `file_id: optional string` + The execution context that produced this tool call. - The ID of the file to be sent to the model. + - `Direct object { type }` - - `image_url: optional string` + - `type: "direct"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `"direct"` - - `prompt_cache_breakpoint: optional object { mode }` + - `Program object { caller_id, 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. + - `caller_id: string` - - `mode: "explicit"` + The call ID of the program item that produced this tool call. - The breakpoint mode. Always `explicit`. + - `type: "program"` - - `"explicit"` + - `"program"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `created_by: optional string` - A file input to the model. + The ID of the entity that created this tool call output. - - `type: "input_file"` + - `output: optional string` - The type of the input item. Always `input_file`. + Optional textual output returned by the apply patch tool. - - `"input_file"` + - `McpCall object { id, arguments, name, 7 more }` - - `detail: optional "auto" or "low" or "high"` + An invocation of a tool on an MCP server. - 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`. + - `id: string` - - `"auto"` + The unique ID of the tool call. - - `"low"` + - `arguments: string` - - `"high"` + A JSON string of the arguments passed to the tool. - - `file_data: optional string` + - `name: string` - The content of the file to be sent to the model. + The name of the tool that was run. - - `file_id: optional string` + - `server_label: string` - The ID of the file to be sent to the model. + The label of the MCP server running the tool. - - `file_url: optional string` + - `type: "mcp_call"` - The URL of the file to be sent to the model. + The type of the item. Always `mcp_call`. - - `filename: optional string` + - `"mcp_call"` - The name of the file to be sent to the model. + - `agent: optional object { agent_name }` - - `prompt_cache_breakpoint: optional object { mode }` + The agent that produced this item. - 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. + - `agent_name: string` - - `mode: "explicit"` + The canonical name of the agent that produced this item. - The breakpoint mode. Always `explicit`. + - `approval_request_id: optional string` - - `"explicit"` + 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. - - `version: optional string` + - `error: optional string` - Optional version of the prompt template. + The error from the tool call, if any. -### Beta Response Queued Event + - `output: optional string` -- `BetaResponseQueuedEvent object { response, sequence_number, type, agent }` + The output from the tool call. - Emitted when a response is queued and waiting to be processed. + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `response: BetaResponse` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - The full response object that is queued. + - `"in_progress"` - - `id: string` + - `"completed"` - Unique identifier for this Response. + - `"incomplete"` - - `created_at: number` + - `"calling"` - Unix timestamp (in seconds) of when this Response was created. + - `"failed"` - - `error: BetaResponseError` + - `McpListTools object { id, server_label, tools, 3 more }` - An error object returned when the model fails to generate a Response. + A list of tools available on an MCP server. - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 17 more` + - `id: string` - The error code for the response. + The unique ID of the list. - - `"server_error"` + - `server_label: string` - - `"rate_limit_exceeded"` + The label of the MCP server. - - `"invalid_prompt"` + - `tools: array of object { input_schema, name, annotations, description }` - - `"data_residency_mismatch"` + The tools available on the server. - - `"bio_policy"` + - `input_schema: unknown` - - `"vector_store_timeout"` + The JSON schema describing the tool's input. - - `"invalid_image"` + - `name: string` - - `"invalid_image_format"` + The name of the tool. - - `"invalid_base64_image"` + - `annotations: optional unknown` - - `"invalid_image_url"` + Additional annotations about the tool. - - `"image_too_large"` + - `description: optional string` - - `"image_too_small"` + The description of the tool. - - `"image_parse_error"` + - `type: "mcp_list_tools"` - - `"image_content_policy_violation"` + The type of the item. Always `mcp_list_tools`. - - `"invalid_image_mode"` + - `"mcp_list_tools"` - - `"image_file_too_large"` + - `agent: optional object { agent_name }` - - `"unsupported_image_media_type"` + The agent that produced this item. - - `"empty_image_file"` + - `agent_name: string` - - `"failed_to_download_image"` + The canonical name of the agent that produced this item. - - `"image_file_not_found"` + - `error: optional string` - - `message: string` + Error message if the server could not list tools. - A human-readable description of the error. + - `McpApprovalRequest object { id, arguments, name, 3 more }` - - `incomplete_details: object { reason }` + A request for human approval of a tool invocation. - Details about why the response is incomplete. + - `id: string` - - `reason: optional "max_output_tokens" or "content_filter"` + The unique ID of the approval request. - The reason why the response is incomplete. + - `arguments: string` - - `"max_output_tokens"` + A JSON string of arguments for the tool. - - `"content_filter"` + - `name: string` - - `instructions: string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + The name of the tool to run. - A system (or developer) message inserted into the model's context. + - `server_label: string` - 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. + The label of the MCP server making the request. - - `string` + - `type: "mcp_approval_request"` - A text input to the model, equivalent to a text input with the - `developer` role. + The type of the item. Always `mcp_approval_request`. - - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + - `"mcp_approval_request"` - A list of one or many input items to the model, containing - different content types. + - `agent: optional object { agent_name }` - - `BetaEasyInputMessage object { content, role, phase, type }` + The agent that produced this 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. Messages with the - `assistant` role are presumed to have been generated by the model in previous - interactions. + - `agent_name: string` - - `content: string or BetaResponseInputMessageContentList` + The canonical name of the agent that produced this item. - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` - - `TextInput = string` + A response to an MCP approval request. - A text input to the model. + - `id: string` - - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` + The unique ID of the approval response - A list of one or many input items to the model, containing different content - types. + - `approval_request_id: string` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + The ID of the approval request being answered. - A text input to the model. + - `approve: boolean` - - `text: string` + Whether the request was approved. - The text input to the model. + - `type: "mcp_approval_response"` - - `type: "input_text"` + The type of the item. Always `mcp_approval_response`. - The type of the input item. Always `input_text`. + - `"mcp_approval_response"` - - `"input_text"` + - `agent: optional object { agent_name }` - - `prompt_cache_breakpoint: optional object { mode }` + The agent that produced this item. - 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. + - `agent_name: string` - - `mode: "explicit"` + The canonical name of the agent that produced this item. - The breakpoint mode. Always `explicit`. + - `reason: optional string` - - `"explicit"` + Optional reason for the decision. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `CustomToolCall object { call_id, input, name, 5 more }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + A call to a custom tool created by the model. - - `detail: "low" or "high" or "auto" or "original"` + - `call_id: string` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + An identifier used to map this custom tool call to a tool call output. - - `"low"` + - `input: string` - - `"high"` + The input for the custom tool call generated by the model. - - `"auto"` + - `name: string` - - `"original"` + The name of the custom tool being called. - - `type: "input_image"` + - `type: "custom_tool_call"` - The type of the input item. Always `input_image`. + The type of the custom tool call. Always `custom_tool_call`. - - `"input_image"` + - `"custom_tool_call"` - - `file_id: optional string` + - `id: optional string` - The ID of the file to be sent to the model. + The unique ID of the custom tool call in the OpenAI platform. - - `image_url: optional string` + - `agent: optional object { agent_name }` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The agent that produced this item. - - `prompt_cache_breakpoint: optional object { mode }` + - `agent_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 canonical name of the agent that produced this item. - - `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 }` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `type: "direct"` - A file input to the model. + - `"direct"` - - `type: "input_file"` + - `Program object { caller_id, type }` - The type of the input item. Always `input_file`. + - `caller_id: string` - - `"input_file"` + The call ID of the program item that produced this tool call. - - `detail: optional "auto" or "low" or "high"` + - `type: "program"` - 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`. + - `"program"` - - `"auto"` + - `namespace: optional string` - - `"low"` + The namespace of the custom tool being called. - - `"high"` + - `CustomToolCallOutput object { id, call_id, output, 5 more }` - - `file_data: optional string` + - `id: string` - The content of the file to be sent to the model. + The unique ID of the custom tool call output item. - - `file_id: optional string` + - `call_id: string` - The ID of the file to be sent to the model. + The call ID, used to map this custom tool call output to a custom tool call. - - `file_url: optional string` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The URL of the file to be sent to the model. + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `filename: optional string` + - `StringOutput = string` - The name of the file to be sent to the model. + A string of the output of the custom tool call. - - `prompt_cache_breakpoint: optional object { mode }` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - 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"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - The breakpoint mode. Always `explicit`. + A text input to the model. - - `"explicit"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `role: "user" or "assistant" or "system" or "developer"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `"user"` + A file input to the model. - - `"assistant"` + - `status: "in_progress" or "completed" or "incomplete"` - - `"system"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"developer"` + - `"in_progress"` - - `phase: optional "commentary" or "final_answer"` + - `"completed"` - 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. + - `"incomplete"` - - `"commentary"` + - `type: "custom_tool_call_output"` - - `"final_answer"` + The type of the custom tool call output. Always `custom_tool_call_output`. - - `type: optional "message"` + - `"custom_tool_call_output"` - The type of the message input. Always `message`. + - `agent: optional object { agent_name }` - - `"message"` + The agent that produced this item. - - `Message object { content, role, agent, 2 more }` + - `agent_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. + The canonical name of the agent that produced this item. - - `content: BetaResponseInputMessageContentList` + - `caller: optional object { type } or object { caller_id, type }` - A list of one or many input items to the model, containing different content - types. + The execution context that produced this tool call. - - `role: "user" or "system" or "developer"` + - `Direct object { type }` - The role of the message input. One of `user`, `system`, or `developer`. + - `type: "direct"` - - `"user"` + The caller type. Always `direct`. - - `"system"` + - `"direct"` - - `"developer"` + - `Program object { caller_id, type }` - - `agent: optional object { agent_name }` + - `caller_id: string` - The agent that produced this item. + The call ID of the program item that produced this tool call. - - `agent_name: string` + - `type: "program"` - The canonical name of the agent that produced this item. + The caller type. Always `program`. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"program"` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `created_by: optional string` - - `"in_progress"` + The identifier of the actor that created the item. - - `"completed"` +### Beta Response Output Item Added Event - - `"incomplete"` +- `BetaResponseOutputItemAddedEvent object { item, output_index, sequence_number, 2 more }` - - `type: optional "message"` + Emitted when a new output item is added. - The type of the message input. Always set to `message`. + - `item: BetaResponseOutputItem` - - `"message"` + The output item that was added. - `BetaResponseOutputMessage object { id, content, role, 4 more }` @@ -147892,36 +146094,66 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The text that was retrieved from the file. - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + - `FunctionCall object { arguments, call_id, name, 6 more }` - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `id: string` + - `arguments: string` - The unique ID of the computer call. + A JSON string of the arguments to pass to the function. - `call_id: string` - An identifier used when responding to the tool call with output. + The unique ID of the function tool call generated by the model. - - `pending_safety_checks: array of object { id, code, message }` + - `name: string` - The pending safety checks for the computer call. + The name of the function to run. - - `id: string` + - `type: "function_call"` - The ID of the pending safety check. + The type of the function tool call. Always `function_call`. - - `code: optional string` + - `"function_call"` - The type of the pending safety check. + - `id: optional string` - - `message: optional string` + The unique ID of the function tool call. - Details about the pending safety check. + - `agent: optional object { agent_name }` - - `status: "in_progress" or "completed" or "incomplete"` + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + - `"program"` + + - `namespace: optional string` + + The namespace of the function to run. + + - `status: optional "in_progress" or "completed" or "incomplete"` The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. @@ -147932,308 +146164,371 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `type: "computer_call"` + - `FunctionCallOutput object { id, call_id, output, 5 more }` - The type of the computer call. Always `computer_call`. + - `id: string` - - `"computer_call"` + The unique ID of the function call tool output. - - `action: optional BetaComputerAction` + - `call_id: string` - A click action. + The unique ID of the function tool call generated by the model. - - `Click object { button, type, x, 2 more }` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - A click action. + The output from the function call generated by your code. + Can be a string or an list of output content. - - `button: "left" or "right" or "wheel" or 2 more` + - `StringOutput = string` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + A string of the output of the function call. - - `"left"` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `"right"` + Text, image, or file output of the function call. - - `"wheel"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `"back"` + A text input to the model. - - `"forward"` + - `text: string` - - `type: "click"` + The text input to the model. - Specifies the event type. For a click action, this property is always `click`. + - `type: "input_text"` - - `"click"` + The type of the input item. Always `input_text`. - - `x: number` + - `"input_text"` - The x-coordinate where the click occurred. + - `prompt_cache_breakpoint: optional object { mode }` - - `y: number` + 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 y-coordinate where the click occurred. + - `mode: "explicit"` - - `keys: optional array of string` + The breakpoint mode. Always `explicit`. - The keys being held while clicking. + - `"explicit"` - - `DoubleClick object { keys, type, x, y }` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - A double click action. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `keys: array of string` + - `detail: "low" or "high" or "auto" or "original"` - The keys being held while double-clicking. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `type: "double_click"` + - `"low"` - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `"high"` - - `"double_click"` + - `"auto"` - - `x: number` + - `"original"` - The x-coordinate where the double click occurred. + - `type: "input_image"` - - `y: number` + The type of the input item. Always `input_image`. - The y-coordinate where the double click occurred. + - `"input_image"` - - `Drag object { path, type, keys }` + - `file_id: optional string` - A drag action. + The ID of the file to be sent to the model. - - `path: array of object { x, y }` + - `image_url: optional string` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `prompt_cache_breakpoint: optional object { mode }` - - `x: number` + 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 x-coordinate. + - `mode: "explicit"` - - `y: number` + The breakpoint mode. Always `explicit`. - The y-coordinate. + - `"explicit"` - - `type: "drag"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - Specifies the event type. For a drag action, this property is always set to `drag`. + A file input to the model. - - `"drag"` + - `type: "input_file"` - - `keys: optional array of string` + The type of the input item. Always `input_file`. - The keys being held while dragging the mouse. + - `"input_file"` - - `Keypress object { keys, type }` + - `detail: optional "auto" or "low" or "high"` - A collection of keypresses the model would like to perform. + 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`. - - `keys: array of string` + - `"auto"` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `"low"` - - `type: "keypress"` + - `"high"` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `file_data: optional string` - - `"keypress"` + The content of the file to be sent to the model. - - `Move object { type, x, y, keys }` + - `file_id: optional string` - A mouse move action. + The ID of the file to be sent to the model. - - `type: "move"` + - `file_url: optional string` - Specifies the event type. For a move action, this property is always set to `move`. + The URL of the file to be sent to the model. - - `"move"` + - `filename: optional string` - - `x: number` + The name of the file to be sent to the model. - The x-coordinate to move to. + - `prompt_cache_breakpoint: optional object { mode }` - - `y: number` + 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 y-coordinate to move to. + - `mode: "explicit"` - - `keys: optional array of string` + The breakpoint mode. Always `explicit`. - The keys being held while moving the mouse. + - `"explicit"` - - `Screenshot object { type }` + - `status: "in_progress" or "completed" or "incomplete"` - A screenshot action. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `type: "screenshot"` + - `"in_progress"` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `"completed"` - - `"screenshot"` + - `"incomplete"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `type: "function_call_output"` - A scroll action. + The type of the function tool call output. Always `function_call_output`. - - `scroll_x: number` + - `"function_call_output"` - The horizontal scroll distance. + - `agent: optional object { agent_name }` - - `scroll_y: number` + The agent that produced this item. - The vertical scroll distance. + - `agent_name: string` - - `type: "scroll"` + The canonical name of the agent that produced this item. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `caller: optional object { type } or object { caller_id, type }` - - `"scroll"` + The execution context that produced this tool call. - - `x: number` + - `Direct object { type }` - The x-coordinate where the scroll occurred. + - `type: "direct"` - - `y: number` + The caller type. Always `direct`. - The y-coordinate where the scroll occurred. + - `"direct"` - - `keys: optional array of string` + - `Program object { caller_id, type }` - The keys being held while scrolling. + - `caller_id: string` - - `Type object { text, type }` + The call ID of the program item that produced this tool call. - An action to type in text. + - `type: "program"` - - `text: string` + The caller type. Always `program`. - The text to type. + - `"program"` - - `type: "type"` + - `created_by: optional string` - Specifies the event type. For a type action, this property is always set to `type`. + The identifier of the actor that created the item. - - `"type"` + - `AgentMessage object { id, author, content, 3 more }` - - `Wait object { type }` + - `id: string` - A wait action. + The unique ID of the agent message. - - `type: "wait"` + - `author: string` - Specifies the event type. For a wait action, this property is always set to `wait`. + The sending agent identity. - - `"wait"` + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - - `actions: optional BetaComputerActionList` + Encrypted content sent between agents. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `Click object { button, type, x, 2 more }` + A text input to the model. - A click action. + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - - `DoubleClick object { keys, type, x, y }` + A text output from the model. - A double click action. + - `Text object { text, type }` - - `Drag object { path, type, keys }` + A text content. - A drag action. + - `text: string` - - `Keypress object { keys, type }` + - `type: "text"` - A collection of keypresses the model would like to perform. + - `"text"` - - `Move object { type, x, y, keys }` + - `SummaryText object { text, type }` - A mouse move action. + A summary text from the model. - - `Screenshot object { type }` + - `text: string` - A screenshot action. + A summary of the reasoning output from the model so far. - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `type: "summary_text"` - A scroll action. + The type of the object. Always `summary_text`. - - `Type object { text, type }` + - `"summary_text"` - An action to type in text. + - `ReasoningText object { text, type }` - - `Wait object { type }` + Reasoning text from the model. - A wait action. + - `text: string` - - `agent: optional object { agent_name }` + The reasoning text from the model. - The agent that produced this item. + - `type: "reasoning_text"` - - `agent_name: string` + The type of the reasoning text. Always `reasoning_text`. - The canonical name of the agent that produced this item. + - `"reasoning_text"` - - `ComputerCallOutput object { call_id, output, type, 4 more }` + - `BetaResponseOutputRefusal object { refusal, type }` - The output of a computer tool call. + A refusal from the model. - - `call_id: string` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - The ID of the computer tool call that produced the output. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` - A computer screenshot image used with the computer use tool. + A screenshot of a computer. - - `type: "computer_screenshot"` + - `detail: "low" or "high" or "auto" or "original"` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"computer_screenshot"` + - `"low"` - - `file_id: optional string` + - `"high"` + + - `"auto"` + + - `"original"` + + - `file_id: string` The identifier of an uploaded file that contains the screenshot. - - `image_url: optional string` + - `image_url: string` The URL of the screenshot image. - - `type: "computer_call_output"` + - `type: "computer_screenshot"` - The type of the computer tool call output. Always `computer_call_output`. + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `"computer_call_output"` + - `"computer_screenshot"` - - `id: optional string` + - `prompt_cache_breakpoint: optional object { mode }` - The ID of the computer tool 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. - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `mode: "explicit"` - The safety checks reported by the API that have been acknowledged by the developer. + The breakpoint mode. Always `explicit`. + + - `"explicit"` + + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `EncryptedContent object { encrypted_content, type }` + + Opaque encrypted content that Responses API decrypts inside trusted model execution. + + - `encrypted_content: string` + + Opaque encrypted content. + + - `type: "encrypted_content"` + + The type of the input item. Always `encrypted_content`. + + - `"encrypted_content"` + + - `recipient: string` + + The destination agent identity. + + - `type: "agent_message"` + + The type of the item. Always `agent_message`. + + - `"agent_message"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `MultiAgentCall object { id, action, arguments, 3 more }` - `id: string` - The ID of the pending safety check. + The unique ID of the multi-agent call item. - - `code: optional string` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - The type of the pending safety check. + The multi-agent action to execute. - - `message: optional string` + - `"spawn_agent"` - Details about the pending safety check. + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` + + - `arguments: string` + + The JSON string of arguments generated for the action. + + - `call_id: string` + + The unique ID linking this call to its output. + + - `type: "multi_agent_call"` + + The type of the multi-agent call. Always `multi_agent_call`. + + - `"multi_agent_call"` - `agent: optional object { agent_name }` @@ -148243,15 +146538,63 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `MultiAgentCallOutput object { id, action, call_id, 3 more }` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `id: string` - - `"in_progress"` + The unique ID of the multi-agent call output item. - - `"completed"` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `"incomplete"` + The multi-agent action that produced this result. + + - `"spawn_agent"` + + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` + + - `call_id: string` + + The unique ID of the multi-agent call. + + - `output: array of BetaResponseOutputText` + + Text output returned by the multi-agent action. + + - `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. + + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + + - `text: string` + + The text output from the model. + + - `type: "output_text"` + + The type of the output text. Always `output_text`. + + - `type: "multi_agent_call_output"` + + The type of the multi-agent result. Always `multi_agent_call_output`. + + - `"multi_agent_call_output"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. - `WebSearchCall object { id, action, status, 2 more }` @@ -148357,349 +146700,360 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `FunctionCall object { arguments, call_id, name, 6 more }` + - `ComputerCall object { id, call_id, pending_safety_checks, 5 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` - - `agent: optional object { agent_name }` + Details about the pending safety check. - The agent that produced this item. + - `status: "in_progress" or "completed" or "incomplete"` - - `agent_name: string` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The canonical name of the agent that produced this item. + - `"in_progress"` - - `caller: optional object { type } or object { caller_id, type }` + - `"completed"` - The execution context that produced this tool call. + - `"incomplete"` - - `Direct object { type }` + - `type: "computer_call"` - - `type: "direct"` + The type of the computer call. Always `computer_call`. - - `"direct"` + - `"computer_call"` - - `Program object { caller_id, type }` + - `action: optional BetaComputerAction` - - `caller_id: string` + A click action. - The call ID of the program item that produced this tool call. + - `Click object { button, type, x, 2 more }` - - `type: "program"` + A click action. - - `"program"` + - `button: "left" or "right" or "wheel" or 2 more` - - `namespace: optional string` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - The namespace of the function to run. + - `"left"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"right"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"wheel"` - - `"in_progress"` + - `"back"` - - `"completed"` + - `"forward"` - - `"incomplete"` + - `type: "click"` - - `FunctionCallOutput object { call_id, output, type, 4 more }` + Specifies the event type. For a click action, this property is always `click`. - The output of a function tool call. + - `"click"` - - `call_id: string` + - `x: number` - The unique ID of the function tool call generated by the model. + The x-coordinate where the click occurred. - - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` + - `y: number` - Text, image, or file output of the function tool call. + The y-coordinate where the click occurred. - - `string` + - `keys: optional array of string` - A JSON string of the output of the function tool call. + The keys being held while clicking. - - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` + - `DoubleClick object { keys, type, x, y }` - An array of content outputs (text, image, file) for the function tool call. + A double click action. - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + - `keys: array of string` - A text input to the model. + The keys being held while double-clicking. - - `text: string` + - `type: "double_click"` - The text input to the model. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `type: "input_text"` + - `"double_click"` - The type of the input item. Always `input_text`. + - `x: number` - - `"input_text"` + The x-coordinate where the double click occurred. - - `prompt_cache_breakpoint: optional object { mode }` + - `y: number` - 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 y-coordinate where the double click occurred. - - `mode: "explicit"` + - `Drag object { path, type, keys }` - The breakpoint mode. Always `explicit`. + A drag action. - - `"explicit"` + - `path: array of object { x, y }` - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - An image input to the model. Learn about [image inputs](/docs/guides/vision) + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `type: "input_image"` + - `x: number` - The type of the input item. Always `input_image`. + The x-coordinate. - - `"input_image"` + - `y: number` - - `detail: optional "low" or "high" or "auto" or "original"` + The y-coordinate. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `type: "drag"` - - `"low"` + Specifies the event type. For a drag action, this property is always set to `drag`. - - `"high"` + - `"drag"` - - `"auto"` + - `keys: optional array of string` - - `"original"` + The keys being held while dragging the mouse. - - `file_id: optional string` + - `Keypress object { keys, type }` - The ID of the file to be sent to the model. + A collection of keypresses the model would like to perform. - - `image_url: optional string` + - `keys: array of 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 combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `prompt_cache_breakpoint: optional object { mode }` + - `type: "keypress"` - 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. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `mode: "explicit"` + - `"keypress"` - The breakpoint mode. Always `explicit`. + - `Move object { type, x, y, keys }` - - `"explicit"` + A mouse move action. - - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` + - `type: "move"` - A file input to the model. + Specifies the event type. For a move action, this property is always set to `move`. - - `type: "input_file"` + - `"move"` - The type of the input item. Always `input_file`. + - `x: number` - - `"input_file"` + The x-coordinate to move to. - - `detail: optional "auto" or "low" or "high"` + - `y: number` - 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 y-coordinate to move to. - - `"auto"` + - `keys: optional array of string` - - `"low"` + The keys being held while moving the mouse. - - `"high"` + - `Screenshot object { type }` - - `file_data: optional string` + A screenshot action. - The base64-encoded data of the file to be sent to the model. + - `type: "screenshot"` - - `file_id: optional string` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - The ID of the file to be sent to the model. + - `"screenshot"` - - `file_url: optional string` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - The URL of the file to be sent to the model. + A scroll action. - - `filename: optional string` + - `scroll_x: number` - The name of the file to be sent to the model. + The horizontal scroll distance. - - `prompt_cache_breakpoint: optional object { mode }` + - `scroll_y: number` - 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 vertical scroll distance. - - `mode: "explicit"` + - `type: "scroll"` - The breakpoint mode. Always `explicit`. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `"explicit"` + - `"scroll"` - - `type: "function_call_output"` + - `x: number` - The type of the function tool call output. Always `function_call_output`. + The x-coordinate where the scroll occurred. - - `"function_call_output"` + - `y: number` - - `id: optional string` + The y-coordinate where the scroll occurred. - The unique ID of the function tool call output. Populated when this item is returned via API. + - `keys: optional array of string` - - `agent: optional object { agent_name }` + The keys being held while scrolling. - The agent that produced this item. + - `Type object { text, type }` - - `agent_name: string` + An action to type in text. - The canonical name of the agent that produced this item. + - `text: string` - - `caller: optional object { type } or object { caller_id, type }` + The text to type. - The execution context that produced this tool call. + - `type: "type"` - - `Direct object { type }` + Specifies the event type. For a type action, this property is always set to `type`. - - `type: "direct"` + - `"type"` - The caller type. Always `direct`. + - `Wait object { type }` - - `"direct"` + A wait action. - - `Program object { caller_id, type }` + - `type: "wait"` - - `caller_id: string` + Specifies the event type. For a wait action, this property is always set to `wait`. - The call ID of the program item that produced this tool call. + - `"wait"` - - `type: "program"` + - `actions: optional BetaComputerActionList` - The caller type. Always `program`. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `"program"` + - `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. + - `DoubleClick object { keys, type, x, y }` - - `"in_progress"` + A double click action. - - `"completed"` + - `Drag object { path, type, keys }` - - `"incomplete"` + A drag action. - - `AgentMessage object { author, content, recipient, 3 more }` + - `Keypress object { keys, type }` - A message routed between agents. + A collection of keypresses the model would like to perform. - - `author: string` + - `Move object { type, x, y, keys }` - The sending agent identity. + A mouse move action. - - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` + - `Screenshot object { type }` - Plaintext, image, or encrypted content sent between agents. + A screenshot action. - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - A text input to the model. + A scroll action. - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + - `Type object { text, type }` - An image input to the model. Learn about [image inputs](/docs/guides/vision) + An action to type in text. - - `EncryptedContent object { encrypted_content, type }` + - `Wait object { type }` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + A wait action. - - `encrypted_content: string` + - `agent: optional object { agent_name }` - Opaque encrypted content. + The agent that produced this item. - - `type: "encrypted_content"` + - `agent_name: string` - The type of the input item. Always `encrypted_content`. + The canonical name of the agent that produced this item. - - `"encrypted_content"` + - `ComputerCallOutput object { id, call_id, output, 5 more }` - - `recipient: string` + - `id: string` - The destination agent identity. + The unique ID of the computer call tool output. - - `type: "agent_message"` + - `call_id: string` - The item type. Always `agent_message`. + The ID of the computer tool call that produced the output. - - `"agent_message"` + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `id: optional string` + A computer screenshot image used with the computer use tool. - The unique ID of this agent message item. + - `type: "computer_screenshot"` - - `agent: optional object { agent_name }` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - The agent that produced this item. + - `"computer_screenshot"` - - `agent_name: string` + - `file_id: optional string` - The canonical name of the agent that produced this item. + The identifier of an uploaded file that contains the screenshot. - - `MultiAgentCall object { action, arguments, call_id, 3 more }` + - `image_url: optional string` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + The URL of the screenshot image. - The multi-agent action that was executed. + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - - `"spawn_agent"` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `"interrupt_agent"` + - `"completed"` - - `"list_agents"` + - `"incomplete"` - - `"send_message"` + - `"failed"` - - `"followup_task"` + - `"in_progress"` - - `"wait_agent"` + - `type: "computer_call_output"` - - `arguments: string` + The type of the computer tool call output. Always `computer_call_output`. - The action arguments as a JSON string. + - `"computer_call_output"` - - `call_id: string` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - The unique ID linking this call to its output. + The safety checks reported by the API that have been acknowledged by the + developer. - - `type: "multi_agent_call"` + - `id: string` - The item type. Always `multi_agent_call`. + The ID of the pending safety check. - - `"multi_agent_call"` + - `code: optional string` - - `id: optional string` + The type of the pending safety check. - The unique ID of this multi-agent call. + - `message: optional string` + + Details about the pending safety check. - `agent: optional object { agent_name }` @@ -148709,127 +147063,139 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `MultiAgentCallOutput object { action, call_id, output, 3 more }` + - `created_by: optional string` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + The identifier of the actor that created the item. - The multi-agent action that produced this result. + - `Reasoning object { id, summary, type, 4 more }` - - `"spawn_agent"` + 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). - - `"interrupt_agent"` + - `id: string` - - `"list_agents"` + The unique identifier of the reasoning content. - - `"send_message"` + - `summary: array of object { text, type }` - - `"followup_task"` + Reasoning summary content. - - `"wait_agent"` + - `text: string` - - `call_id: string` + A summary of the reasoning output from the model so far. - The unique ID of the multi-agent call. + - `type: "summary_text"` - - `output: array of object { text, type, annotations }` + The type of the object. Always `summary_text`. - Text output returned by the multi-agent action. + - `"summary_text"` - - `text: string` + - `type: "reasoning"` - The text content. + The type of the object. Always `reasoning`. - - `type: "output_text"` + - `"reasoning"` - The content type. Always `output_text`. + - `agent: optional object { agent_name }` - - `"output_text"` + The agent that produced this item. - - `annotations: optional 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 }` + - `agent_name: string` - Citations associated with the text content. + The canonical name of the agent that produced this item. - - `FileCitation object { file_id, filename, index, type }` + - `content: optional array of object { text, type }` - - `file_id: string` + Reasoning text content. - The ID of the file. + - `text: string` - - `filename: string` + The reasoning text from the model. - The filename of the file cited. + - `type: "reasoning_text"` - - `index: number` + The type of the reasoning text. Always `reasoning_text`. - The index of the file in the list of files. + - `"reasoning_text"` - - `type: "file_citation"` + - `encrypted_content: optional string` - The citation type. Always `file_citation`. + 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. - - `"file_citation"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `URLCitation object { end_index, start_index, title, 2 more }` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `end_index: number` + - `"in_progress"` - The index of the last character of the citation in the message. + - `"completed"` - - `start_index: number` + - `"incomplete"` - The index of the first character of the citation in the message. + - `Program object { id, call_id, code, 3 more }` - - `title: string` + - `id: string` - The title of the cited resource. + The unique ID of the program item. - - `type: "url_citation"` + - `call_id: string` - The citation type. Always `url_citation`. + The stable call ID of the program item. - - `"url_citation"` + - `code: string` - - `url: string` + The JavaScript source executed by programmatic tool calling. - The URL of the cited resource. + - `fingerprint: string` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + Opaque program replay fingerprint that must be round-tripped. - - `container_id: string` + - `type: "program"` - The ID of the container. + The type of the item. Always `program`. - - `end_index: number` + - `"program"` - The index of the last character of the citation in the message. + - `agent: optional object { agent_name }` - - `file_id: string` + The agent that produced this item. - The ID of the container file. + - `agent_name: string` - - `filename: string` + The canonical name of the agent that produced this item. - The filename of the container file cited. + - `ProgramOutput object { id, call_id, result, 3 more }` - - `start_index: number` + - `id: string` - The index of the first character of the citation in the message. + The unique ID of the program output item. - - `type: "container_file_citation"` + - `call_id: string` - The citation type. Always `container_file_citation`. + The call ID of the program item. - - `"container_file_citation"` + - `result: string` - - `type: "multi_agent_call_output"` + The result produced by the program item. - The item type. Always `multi_agent_call_output`. + - `status: "completed" or "incomplete"` - - `"multi_agent_call_output"` + The terminal status of the program output item. - - `id: optional string` + - `"completed"` - The unique ID of this multi-agent call output. + - `"incomplete"` + + - `type: "program_output"` + + The type of the item. Always `program_output`. + + - `"program_output"` - `agent: optional object { agent_name }` @@ -148839,21 +147205,43 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `ToolSearchCall object { arguments, type, id, 4 more }` + - `ToolSearchCall object { id, arguments, call_id, 5 more }` + + - `id: string` + + The unique ID of the tool search call item. - `arguments: unknown` - The arguments supplied to the tool search call. + Arguments used for the tool search call. - - `type: "tool_search_call"` + - `call_id: string` - The item type. Always `tool_search_call`. + The unique ID of the tool search call generated by the model. - - `"tool_search_call"` + - `execution: "server" or "client"` - - `id: optional string` + Whether tool search was executed by the server or by the client. - The unique ID of this tool search call. + - `"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"` - `agent: optional object { agent_name }` @@ -148863,11 +147251,21 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `call_id: optional string` + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `ToolSearchOutput object { id, call_id, execution, 5 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: optional "server" or "client"` + - `execution: "server" or "client"` Whether tool search was executed by the server or by the client. @@ -148875,9 +147273,9 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"client"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `status: "in_progress" or "completed" or "incomplete"` - The status of the tool search call. + The status of the tool search output item that was recorded. - `"in_progress"` @@ -148885,11 +147283,9 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `ToolSearchOutput object { tools, type, id, 4 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. + The loaded tool definitions returned by tool search. - `Function object { name, parameters, strict, 5 more }` @@ -150032,14 +148428,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "tool_search_output"` - The item type. Always `tool_search_output`. + The type of the item. Always `tool_search_output`. - `"tool_search_output"` - - `id: optional string` - - The unique ID of this tool search output. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -150048,39 +148440,39 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `call_id: optional string` - - The unique ID of the tool search call generated by the model. + - `created_by: optional string` - - `execution: optional "server" or "client"` + The identifier of the actor that created the item. - Whether tool search was executed by the server or by the client. + - `AdditionalTools object { id, role, tools, 2 more }` - - `"server"` + - `id: string` - - `"client"` + The unique ID of the additional tools item. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `role: "unknown" or "user" or "assistant" or 5 more` - The status of the tool search output. + The role that provided the additional tools. - - `"in_progress"` + - `"unknown"` - - `"completed"` + - `"user"` - - `"incomplete"` + - `"assistant"` - - `AdditionalTools object { role, tools, type, 2 more }` + - `"system"` - - `role: "developer"` + - `"critic"` - The role that provided the additional tools. Only `developer` is supported. + - `"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` - A list of additional tools made available at this item. + The additional tool definitions made available at this item. - `Function object { name, parameters, strict, 5 more }` @@ -151073,14 +149465,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "additional_tools"` - The item type. Always `additional_tools`. + The type of the item. Always `additional_tools`. - `"additional_tools"` - - `id: optional string` - - The unique ID of this additional tools item. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -151089,83 +149477,17 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `Reasoning object { id, summary, type, 4 more }` + - `Compaction object { id, encrypted_content, type, 2 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). + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - `id: string` - The unique identifier of the reasoning content. - - - `summary: array of object { text, type }` - - 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"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `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, agent }` - - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + The unique ID of the compaction item. - `encrypted_content: string` - The encrypted content of the compaction summary. + The encrypted content that was produced by compaction. - `type: "compaction"` @@ -151173,10 +149495,6 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"compaction"` - - `id: optional string` - - The ID of the compaction item. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -151185,6 +149503,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. + - `created_by: optional string` + + The identifier of the actor that created the item. + - `ImageGenerationCall object { id, result, status, 2 more }` An image generation request made by the model. @@ -151402,9 +149724,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `ShellCall object { action, call_id, type, 5 more }` + - `ShellCall object { id, action, call_id, 6 more }` - A tool representing a request to execute one or more shell commands. + 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 }` @@ -151412,30 +149738,60 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `commands: array of string` - Ordered shell commands for the execution environment to run. - - - `max_output_length: optional number` + - `max_output_length: number` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + Optional maximum number of characters to return from each command. - - `timeout_ms: optional number` + - `timeout_ms: number` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + Optional timeout in milliseconds for the commands. - `call_id: string` The unique ID of the shell tool call generated by the model. + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + + Represents the use of a local environment to perform shell actions. + + - `BetaResponseLocalEnvironment object { type }` + + Represents the use of a local environment to perform shell actions. + + - `type: "local"` + + The environment type. Always `local`. + + - `"local"` + + - `BetaResponseContainerReference 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. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -151452,8 +149808,6 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "direct"` - The caller type. Always `direct`. - - `"direct"` - `Program object { caller_id, type }` @@ -151464,43 +149818,35 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "program"` - The caller type. Always `program`. - - `"program"` - - `environment: optional BetaLocalEnvironment or BetaContainerReference` - - The environment to execute the shell commands in. - - - `BetaLocalEnvironment object { type, skills }` - - - `BetaContainerReference object { container_id, type }` - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `created_by: optional string` - - `"in_progress"` + The ID of the entity that created this tool call. - - `"completed"` + - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` - - `"incomplete"` + The output of a shell tool call that was emitted. - - `ShellCallOutput object { call_id, output, type, 5 more }` + - `id: string` - The streamed output items emitted by a shell tool call. + The unique ID of the shell call output. Populated when this item is returned via API. - `call_id: string` The unique ID of the shell tool call generated by the model. - - `output: array of BetaResponseFunctionShellCallOutputContent` + - `max_output_length: number` - Captured chunks of stdout and stderr output, along with their associated outcomes. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + + - `output: array of object { outcome, stderr, stdout, created_by }` + + An array of shell call output contents - `outcome: object { type } or object { exit_code, type }` - The exit or timeout outcome associated with this shell call. + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - `Timeout object { type }` @@ -151518,7 +149864,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `exit_code: number` - The exit code returned by the shell process. + Exit code from the shell process. - `type: "exit"` @@ -151528,21 +149874,31 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `stderr: string` - Captured stderr output for the shell call. + The standard error output that was captured. - `stdout: string` - Captured stdout output for the shell call. + The standard output that was captured. - - `type: "shell_call_output"` + - `created_by: optional string` - The type of the item. Always `shell_call_output`. + The identifier of the actor that created the item. - - `"shell_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 shell 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"` - `agent: optional object { agent_name }` @@ -151560,8 +149916,6 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "direct"` - The caller type. Always `direct`. - - `"direct"` - `Program object { caller_id, type }` @@ -151572,27 +149926,19 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "program"` - The caller type. Always `program`. - - `"program"` - - `max_output_length: optional number` - - The maximum number of UTF-8 characters captured for this shell call's combined output. - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the shell call output. + - `created_by: optional string` - - `"in_progress"` + The identifier of the actor that created the item. - - `"completed"` + - `ApplyPatchCall object { id, call_id, operation, 5 more }` - - `"incomplete"` + A tool call that applies file diffs by creating, deleting, or updating files. - - `ApplyPatchCall object { call_id, operation, status, 4 more }` + - `id: string` - A tool call representing a request to create, delete, or update files using diff patches. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - `call_id: string` @@ -151600,55 +149946,55 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - The specific create, delete, or update instruction for the apply_patch tool call. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - `CreateFile object { diff, path, type }` - Instruction for creating a new file via the apply_patch tool. + Instruction describing how to create a file via the apply_patch tool. - `diff: string` - Unified diff content to apply when creating the file. + Diff to apply. - `path: string` - Path of the file to create relative to the workspace root. + Path of the file to create. - `type: "create_file"` - The operation type. Always `create_file`. + Create a new file with the provided diff. - `"create_file"` - `DeleteFile object { path, type }` - Instruction for deleting an existing file via the apply_patch tool. + Instruction describing how to delete a file via the apply_patch tool. - `path: string` - Path of the file to delete relative to the workspace root. + Path of the file to delete. - `type: "delete_file"` - The operation type. Always `delete_file`. + Delete the specified file. - `"delete_file"` - `UpdateFile object { diff, path, type }` - Instruction for updating an existing file via the apply_patch tool. + Instruction describing how to update a file via the apply_patch tool. - `diff: string` - Unified diff content to apply to the existing file. + Diff to apply. - `path: string` - Path of the file to update relative to the workspace root. + Path of the file to update. - `type: "update_file"` - The operation type. Always `update_file`. + Update an existing file with the provided diff. - `"update_file"` @@ -151666,10 +150012,6 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"apply_patch_call"` - - `id: optional string` - - The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -151686,8 +150028,6 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "direct"` - The caller type. Always `direct`. - - `"direct"` - `Program object { caller_id, type }` @@ -151698,13 +150038,19 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "program"` - The caller type. Always `program`. - - `"program"` - - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` + - `created_by: optional string` - The streamed output emitted by an apply patch tool call. + The ID of the entity that created this tool call. + + - `ApplyPatchCallOutput object { id, call_id, status, 5 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` @@ -151724,10 +150070,6 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"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. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -151744,8 +150086,6 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "direct"` - The caller type. Always `direct`. - - `"direct"` - `Program object { caller_id, type }` @@ -151756,13 +150096,76 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "program"` - The caller type. Always `program`. - - `"program"` + - `created_by: optional string` + + The ID of the entity that created this tool call output. + - `output: optional string` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + Optional textual output returned by the apply patch tool. + + - `McpCall object { id, arguments, name, 7 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"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `approval_request_id: optional string` + + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + + - `error: optional string` + + The error from the tool call, if any. + + - `output: optional string` + + The output from the tool call. + + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"calling"` + + - `"failed"` - `McpListTools object { id, server_label, tools, 3 more }` @@ -151848,10 +150251,14 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` + - `McpApprovalResponse object { id, approval_request_id, approve, 3 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. @@ -151866,10 +150273,6 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"mcp_approval_response"` - - `id: optional string` - - The unique ID of the approval response - - `agent: optional object { agent_name }` The agent that produced this item. @@ -151882,31 +150285,31 @@ curl -X POST https://api.openai.com/v1/responses/compact \ Optional reason for the decision. - - `McpCall object { id, arguments, name, 7 more }` + - `CustomToolCall object { call_id, input, name, 5 more }` - An invocation of a tool on an MCP server. + A call to a custom tool created by the model. - - `id: string` + - `call_id: string` - The unique ID of the tool call. + An identifier used to map this custom tool call to a tool call output. - - `arguments: string` + - `input: string` - A JSON string of the arguments passed to the tool. + The input for the custom tool call generated by the model. - `name: string` - The name of the tool that was run. + The name of the custom tool being called. - - `server_label: string` + - `type: "custom_tool_call"` - The label of the MCP server running the tool. + The type of the custom tool call. Always `custom_tool_call`. - - `type: "mcp_call"` + - `"custom_tool_call"` - The type of the item. Always `mcp_call`. + - `id: optional string` - - `"mcp_call"` + The unique ID of the custom tool call in the OpenAI platform. - `agent: optional object { agent_name }` @@ -151916,36 +150319,35 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `approval_request_id: optional string` + - `caller: optional object { type } or object { caller_id, type }` - 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 execution context that produced this tool call. - - `error: optional string` + - `Direct object { type }` - The error from the tool call, if any. + - `type: "direct"` - - `output: optional string` + - `"direct"` - The output from the tool call. + - `Program object { caller_id, type }` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `caller_id: string` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The call ID of the program item that produced this tool call. - - `"in_progress"` + - `type: "program"` - - `"completed"` + - `"program"` - - `"incomplete"` + - `namespace: optional string` - - `"calling"` + The namespace of the custom tool being called. - - `"failed"` + - `CustomToolCallOutput object { id, call_id, output, 5 more }` - - `CustomToolCallOutput object { call_id, output, type, 3 more }` + - `id: string` - The output of a custom tool call from your code, being sent back to the model. + The unique ID of the custom tool call output item. - `call_id: string` @@ -151976,16 +150378,23 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -152018,407 +150427,238 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"program"` - - `CustomToolCall object { call_id, input, name, 5 more }` - - A call to a custom tool created by the model. - - - `call_id: string` - - An identifier used to map this custom tool call to a tool call output. - - - `input: string` - - The input for the custom tool call generated by the model. - - - `name: string` - - The name of the custom tool being called. - - - `type: "custom_tool_call"` - - The type of the custom tool call. Always `custom_tool_call`. - - - `"custom_tool_call"` - - - `id: optional string` - - The unique ID of the custom tool call in the OpenAI platform. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `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. - - - `CompactionTrigger object { type, agent }` - - Compacts the current context. Must be the final input item. - - - `type: "compaction_trigger"` - - The type of the item. Always `compaction_trigger`. - - - `"compaction_trigger"` + - `created_by: optional string` - - `agent: optional object { agent_name }` + The identifier of the actor that created the item. - The agent that produced this item. + - `output_index: number` - - `agent_name: string` + The index of the output item that was added. - The canonical name of the agent that produced this item. + - `sequence_number: number` - - `ItemReference object { id, agent, type }` + The sequence number of this event. - An internal identifier for an item to reference. + - `type: "response.output_item.added"` - - `id: string` + The type of the event. Always `response.output_item.added`. - The ID of the item to reference. + - `"response.output_item.added"` - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `type: optional "item_reference"` - - The type of item to reference. Always `item_reference`. - - - `"item_reference"` - - - `Program object { id, call_id, code, 3 more }` - - - `id: string` - - The unique ID of this program item. - - - `call_id: string` - - The stable call ID of the program item. - - - `code: string` - - The JavaScript source executed by programmatic tool calling. - - - `fingerprint: string` - - Opaque program replay fingerprint that must be round-tripped. - - - `type: "program"` - - The item type. Always `program`. +### Beta Response Output Item Done Event - - `"program"` +- `BetaResponseOutputItemDoneEvent object { item, output_index, sequence_number, 2 more }` - - `agent: optional object { agent_name }` + Emitted when an output item is marked done. - The agent that produced this item. + - `item: BetaResponseOutputItem` - - `agent_name: string` + The output item that was marked done. - The canonical name of the agent that produced this item. + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - - `ProgramOutput object { id, call_id, result, 3 more }` + An output message from the model. - `id: string` - The unique ID of this program output item. - - - `call_id: string` - - The call ID of the program item. - - - `result: string` - - The result produced by the program item. - - - `status: "completed" or "incomplete"` - - The terminal status of the program output. - - - `"completed"` - - - `"incomplete"` - - - `type: "program_output"` - - The item type. Always `program_output`. - - - `"program_output"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `metadata: map[string]` - - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. - - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. - - - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - - Model ID used to generate the response, like `gpt-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. - - - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` - - Model ID used to generate the response, like `gpt-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. - - - `"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"` - - - `"gpt-5.2"` - - - `"gpt-5.2-2025-12-11"` + The unique ID of the output message. - - `"gpt-5.2-chat-latest"` + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - - `"gpt-5.2-pro"` + The content of the output message. - - `"gpt-5.2-pro-2025-12-11"` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - - `"gpt-5.1"` + A text output from the model. - - `"gpt-5.1-2025-11-13"` + - `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.1-codex"` + The annotations of the text output. - - `"gpt-5.1-mini"` + - `FileCitation object { file_id, filename, index, type }` - - `"gpt-5.1-chat-latest"` + A citation to a file. - - `"gpt-5"` + - `file_id: string` - - `"gpt-5-mini"` + The ID of the file. - - `"gpt-5-nano"` + - `filename: string` - - `"gpt-5-2025-08-07"` + The filename of the file cited. - - `"gpt-5-mini-2025-08-07"` + - `index: number` - - `"gpt-5-nano-2025-08-07"` + The index of the file in the list of files. - - `"gpt-5-chat-latest"` + - `type: "file_citation"` - - `"gpt-4.1"` + The type of the file citation. Always `file_citation`. - - `"gpt-4.1-mini"` + - `"file_citation"` - - `"gpt-4.1-nano"` + - `URLCitation object { end_index, start_index, title, 2 more }` - - `"gpt-4.1-2025-04-14"` + A citation for a web resource used to generate a model response. - - `"gpt-4.1-mini-2025-04-14"` + - `end_index: number` - - `"gpt-4.1-nano-2025-04-14"` + The index of the last character of the URL citation in the message. - - `"o4-mini"` + - `start_index: number` - - `"o4-mini-2025-04-16"` + The index of the first character of the URL citation in the message. - - `"o3"` + - `title: string` - - `"o3-2025-04-16"` + The title of the web resource. - - `"o3-mini"` + - `type: "url_citation"` - - `"o3-mini-2025-01-31"` + The type of the URL citation. Always `url_citation`. - - `"o1"` + - `"url_citation"` - - `"o1-2024-12-17"` + - `url: string` - - `"o1-preview"` + The URL of the web resource. - - `"o1-preview-2024-09-12"` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - - `"o1-mini"` + A citation for a container file used to generate a model response. - - `"o1-mini-2024-09-12"` + - `container_id: string` - - `"gpt-4o"` + The ID of the container file. - - `"gpt-4o-2024-11-20"` + - `end_index: number` - - `"gpt-4o-2024-08-06"` + The index of the last character of the container file citation in the message. - - `"gpt-4o-2024-05-13"` + - `file_id: string` - - `"gpt-4o-audio-preview"` + The ID of the file. - - `"gpt-4o-audio-preview-2024-10-01"` + - `filename: string` - - `"gpt-4o-audio-preview-2024-12-17"` + The filename of the container file cited. - - `"gpt-4o-audio-preview-2025-06-03"` + - `start_index: number` - - `"gpt-4o-mini-audio-preview"` + The index of the first character of the container file citation in the message. - - `"gpt-4o-mini-audio-preview-2024-12-17"` + - `type: "container_file_citation"` - - `"gpt-4o-search-preview"` + The type of the container file citation. Always `container_file_citation`. - - `"gpt-4o-mini-search-preview"` + - `"container_file_citation"` - - `"gpt-4o-search-preview-2025-03-11"` + - `FilePath object { file_id, index, type }` - - `"gpt-4o-mini-search-preview-2025-03-11"` + A path to a file. - - `"chatgpt-4o-latest"` + - `file_id: string` - - `"codex-mini-latest"` + The ID of the file. - - `"gpt-4o-mini"` + - `index: number` - - `"gpt-4o-mini-2024-07-18"` + The index of the file in the list of files. - - `"gpt-4-turbo"` + - `type: "file_path"` - - `"gpt-4-turbo-2024-04-09"` + The type of the file path. Always `file_path`. - - `"gpt-4-0125-preview"` + - `"file_path"` - - `"gpt-4-turbo-preview"` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - - `"gpt-4-1106-preview"` + - `token: string` - - `"gpt-4-vision-preview"` + - `bytes: array of number` - - `"gpt-4"` + - `logprob: number` - - `"gpt-4-0314"` + - `top_logprobs: array of object { token, bytes, logprob }` - - `"gpt-4-0613"` + - `token: string` - - `"gpt-4-32k"` + - `bytes: array of number` - - `"gpt-4-32k-0314"` + - `logprob: number` - - `"gpt-4-32k-0613"` + - `text: string` - - `"gpt-3.5-turbo"` + The text output from the model. - - `"gpt-3.5-turbo-16k"` + - `type: "output_text"` - - `"gpt-3.5-turbo-0301"` + The type of the output text. Always `output_text`. - - `"gpt-3.5-turbo-0613"` + - `"output_text"` - - `"gpt-3.5-turbo-1106"` + - `BetaResponseOutputRefusal object { refusal, type }` - - `"gpt-3.5-turbo-0125"` + A refusal from the model. - - `"gpt-3.5-turbo-16k-0613"` + - `refusal: string` - - `"o1-pro"` + The refusal explanation from the model. - - `"o1-pro-2025-03-19"` + - `type: "refusal"` - - `"o3-pro"` + The type of the refusal. Always `refusal`. - - `"o3-pro-2025-06-10"` + - `"refusal"` - - `"o3-deep-research"` + - `role: "assistant"` - - `"o3-deep-research-2025-06-26"` + The role of the output message. Always `assistant`. - - `"o4-mini-deep-research"` + - `"assistant"` - - `"o4-mini-deep-research-2025-06-26"` + - `status: "in_progress" or "completed" or "incomplete"` - - `"computer-use-preview"` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `"computer-use-preview-2025-03-11"` + - `"in_progress"` - - `"gpt-5-codex"` + - `"completed"` - - `"gpt-5-pro"` + - `"incomplete"` - - `"gpt-5-pro-2025-10-06"` + - `type: "message"` - - `"gpt-5.1-codex-max"` + The type of the output message. Always `message`. - - `string` + - `"message"` - - `object: "response"` + - `agent: optional object { agent_name }` - The object type of this resource - always set to `response`. + The agent that produced this item. - - `"response"` + - `agent_name: string` - - `output: array of BetaResponseOutputItem` + The canonical name of the agent that produced this item. - 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. - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + - `"commentary"` - An output message from the model. + - `"final_answer"` - `FileSearchCall object { id, queries, status, 3 more }` @@ -152593,14 +150833,112 @@ curl -X POST https://api.openai.com/v1/responses/compact \ A text input to the model. + - `text: string` + + The text input to the model. + + - `type: "input_text"` + + The type of the input item. Always `input_text`. + + - `"input_text"` + + - `prompt_cache_breakpoint: optional object { mode }` + + Marks the exact end of a reusable prompt prefix. The breakpoint inherits its TTL from the request's `prompt_cache_options.ttl`; the boundary is not rounded to a token block. + + - `mode: "explicit"` + + The breakpoint mode. Always `explicit`. + + - `"explicit"` + - `BetaResponseInputImage 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"` + + - `"high"` + + - `"auto"` + + - `"original"` + + - `type: "input_image"` + + The type of the input item. Always `input_image`. + + - `"input_image"` + + - `file_id: optional string` + + The ID of the file to be sent to the model. + + - `image_url: optional string` + + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + + - `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"` + - `BetaResponseInputFile 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"` + - `status: "in_progress" or "completed" or "incomplete"` The status of the item. One of `in_progress`, `completed`, or @@ -153054,11 +151392,238 @@ curl -X POST https://api.openai.com/v1/responses/compact \ A click action. + - `Click object { button, type, x, 2 more }` + + A click action. + + - `button: "left" or "right" or "wheel" or 2 more` + + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + + - `"left"` + + - `"right"` + + - `"wheel"` + + - `"back"` + + - `"forward"` + + - `type: "click"` + + Specifies the event type. For a click action, this property is always `click`. + + - `"click"` + + - `x: number` + + The x-coordinate where the click occurred. + + - `y: number` + + The y-coordinate where the click occurred. + + - `keys: optional array of string` + + The keys being held while clicking. + + - `DoubleClick object { keys, type, x, y }` + + A double click action. + + - `keys: array of string` + + The keys being held while double-clicking. + + - `type: "double_click"` + + Specifies the event type. For a double click action, this property is always set to `double_click`. + + - `"double_click"` + + - `x: number` + + The x-coordinate where the double click occurred. + + - `y: number` + + The y-coordinate where the double click occurred. + + - `Drag object { path, type, keys }` + + A drag action. + + - `path: array of object { x, y }` + + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` + + - `x: number` + + The x-coordinate. + + - `y: number` + + The y-coordinate. + + - `type: "drag"` + + Specifies the event type. For a drag action, this property is always set to `drag`. + + - `"drag"` + + - `keys: optional array of string` + + The keys being held while dragging the mouse. + + - `Keypress object { keys, type }` + + A collection of keypresses the model would like to perform. + + - `keys: array of string` + + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + + - `type: "keypress"` + + Specifies the event type. For a keypress action, this property is always set to `keypress`. + + - `"keypress"` + + - `Move object { type, x, y, keys }` + + A mouse move action. + + - `type: "move"` + + Specifies the event type. For a move action, this property is always set to `move`. + + - `"move"` + + - `x: number` + + The x-coordinate to move to. + + - `y: number` + + The y-coordinate to move to. + + - `keys: optional array of string` + + The keys being held while moving the mouse. + + - `Screenshot object { type }` + + A screenshot action. + + - `type: "screenshot"` + + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + + - `"screenshot"` + + - `Scroll object { scroll_x, scroll_y, type, 3 more }` + + A scroll action. + + - `scroll_x: number` + + The horizontal scroll distance. + + - `scroll_y: number` + + The vertical scroll distance. + + - `type: "scroll"` + + Specifies the event type. For a scroll action, this property is always set to `scroll`. + + - `"scroll"` + + - `x: number` + + The x-coordinate where the scroll occurred. + + - `y: number` + + The y-coordinate where the scroll occurred. + + - `keys: optional array of string` + + The keys being held while scrolling. + + - `Type object { text, type }` + + An action to type in text. + + - `text: string` + + The text to type. + + - `type: "type"` + + Specifies the event type. For a type action, this property is always set to `type`. + + - `"type"` + + - `Wait object { type }` + + A wait action. + + - `type: "wait"` + + Specifies the event type. For a wait action, this property is always set to `wait`. + + - `"wait"` + - `actions: optional BetaComputerActionList` Flattened batched actions for `computer_use`. Each action includes an `type` discriminator and action-specific fields. + - `Click object { button, type, x, 2 more }` + + A click action. + + - `DoubleClick object { keys, type, x, y }` + + A double click action. + + - `Drag object { path, type, keys }` + + A drag action. + + - `Keypress object { keys, type }` + + A collection of keypresses the model would like to perform. + + - `Move object { type, x, y, keys }` + + A mouse move action. + + - `Screenshot object { type }` + + A screenshot action. + + - `Scroll object { scroll_x, scroll_y, type, 3 more }` + + A scroll action. + + - `Type object { text, type }` + + An action to type in text. + + - `Wait object { type }` + + A wait action. + - `agent: optional object { agent_name }` The agent that produced this item. @@ -153081,6 +151646,21 @@ curl -X POST https://api.openai.com/v1/responses/compact \ A computer screenshot image used with the computer use tool. + - `type: "computer_screenshot"` + + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. + + - `"computer_screenshot"` + + - `file_id: optional string` + + The identifier of an uploaded file that contains the screenshot. + + - `image_url: optional string` + + The URL of the screenshot image. + - `status: "completed" or "incomplete" or "failed" or "in_progress"` The status of the message input. One of `in_progress`, `completed`, or @@ -153868,8 +152448,40 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `BetaContainerNetworkPolicyDisabled object { type }` + - `type: "disabled"` + + Disable outbound network access. Always `disabled`. + + - `"disabled"` + - `BetaContainerNetworkPolicyAllowlist 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 BetaContainerNetworkPolicyDomainSecret` + + 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`. @@ -154050,10 +152662,128 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `BetaContainerAuto 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 BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `BetaContainerNetworkPolicyDisabled object { type }` + + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `skills: optional array of BetaSkillReference or BetaInlineSkill` + + An optional list of skills referenced by id or inline data. + + - `BetaSkillReference 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. + + - `BetaInlineSkill object { description, name, source, type }` + + - `description: string` + + The description of the skill. + + - `name: string` + + The name of the skill. + + - `source: BetaInlineSkillSource` + + 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"` + - `BetaLocalEnvironment object { type, skills }` + - `type: "local"` + + Use a local computer environment. + + - `"local"` + + - `skills: optional array of BetaLocalSkill` + + 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. + - `BetaContainerReference 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) @@ -156343,5095 +155073,5325 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The identifier of the actor that created the item. - - `parallel_tool_calls: boolean` + - `output_index: number` - Whether to allow the model to run tool calls in parallel. + The index of the output item that was marked done. - - `temperature: number` + - `sequence_number: number` - 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 sequence number of this event. - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + - `type: "response.output_item.done"` - 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 type of the event. Always `response.output_item.done`. - - `BetaToolChoiceOptions = "none" or "auto" or "required"` + - `"response.output_item.done"` - Controls which (if any) tool is called by the model. + - `agent: optional object { agent_name }` - `none` means the model will not call any tool and instead generates a message. + The agent that owns this multi-agent streaming event. - `auto` means the model can pick between generating a message or calling one or - more tools. + - `agent_name: string` - `required` means the model must call one or more tools. + The canonical name of the agent that produced this item. - - `"none"` +### Beta Response Output Message - - `"auto"` +- `BetaResponseOutputMessage object { id, content, role, 4 more }` - - `"required"` + An output message from the model. - - `BetaToolChoiceAllowed object { mode, tools, type }` + - `id: string` - Constrains the tools available to the model to a pre-defined set. + The unique ID of the output message. - - `mode: "auto" or "required"` + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - Constrains the tools available to the model to a pre-defined set. + The content of the output message. - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - `required` requires the model to call one or more of the allowed tools. + A text output from the model. - - `"auto"` + - `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 }` - - `"required"` + The annotations of the text output. - - `tools: array of map[unknown]` + - `FileCitation object { file_id, filename, index, type }` - A list of tool definitions that the model should be allowed to call. + A citation to a file. - For the Responses API, the list of tool definitions might look like: + - `file_id: string` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + The ID of the file. - - `type: "allowed_tools"` + - `filename: string` - Allowed tool configuration type. Always `allowed_tools`. + The filename of the file cited. - - `"allowed_tools"` + - `index: number` - - `BetaToolChoiceTypes object { type }` + The index of the file in the list of files. - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](/docs/guides/tools). + - `type: "file_citation"` - - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + The type of the file citation. Always `file_citation`. - The type of hosted tool the model should to use. Learn more about - [built-in tools](/docs/guides/tools). + - `"file_citation"` - Allowed values are: + - `URLCitation object { end_index, start_index, title, 2 more }` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + A citation for a web resource used to generate a model response. - - `"file_search"` + - `end_index: number` - - `"web_search_preview"` + The index of the last character of the URL citation in the message. - - `"computer"` + - `start_index: number` - - `"computer_use_preview"` + The index of the first character of the URL citation in the message. - - `"computer_use"` + - `title: string` - - `"web_search_preview_2025_03_11"` + 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"` + + - `BetaResponseOutputRefusal 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"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `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"` + +### Beta Response Output Refusal + +- `BetaResponseOutputRefusal 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"` + +### Beta Response Output Text + +- `BetaResponseOutputText 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"` + +### Beta Response Output Text Annotation Added Event + +- `BetaResponseOutputTextAnnotationAddedEvent object { annotation, annotation_index, content_index, 5 more }` + + Emitted when an annotation is added to output text content. + + - `annotation: unknown` + + The annotation object being added. (See annotation schema for details.) + + - `annotation_index: number` + + The index of the annotation within the content part. + + - `content_index: number` + + The index of the content part within the output item. + + - `item_id: string` - - `"image_generation"` + The unique identifier of the item to which the annotation is being added. - - `"code_interpreter"` + - `output_index: number` - - `BetaToolChoiceFunction object { name, type }` + The index of the output item in the response's output array. - Use this option to force the model to call a specific function. + - `sequence_number: number` - - `name: string` + The sequence number of this event. - The name of the function to call. + - `type: "response.output_text.annotation.added"` - - `type: "function"` + The type of the event. Always 'response.output_text.annotation.added'. - For function calling, the type is always `function`. + - `"response.output_text.annotation.added"` - - `"function"` + - `agent: optional object { agent_name }` - - `BetaToolChoiceMcp object { server_label, type, name }` + The agent that owns this multi-agent streaming event. - Use this option to force the model to call a specific tool on a remote MCP server. + - `agent_name: string` - - `server_label: string` + The canonical name of the agent that produced this item. - The label of the MCP server to use. +### Beta Response Prompt - - `type: "mcp"` +- `BetaResponsePrompt object { id, variables, version }` - For MCP tools, the type is always `mcp`. + Reference to a prompt template and its variables. + [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). - - `"mcp"` + - `id: string` - - `name: optional string` + The unique identifier of the prompt template to use. - The name of the tool to call on the server. + - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` - - `BetaToolChoiceCustom object { name, type }` + 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. - Use this option to force the model to call a specific custom tool. + - `string` - - `name: string` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - The name of the custom tool to call. + A text input to the model. - - `type: "custom"` + - `text: string` - For custom tool calling, the type is always `custom`. + The text input to the model. - - `"custom"` + - `type: "input_text"` - - `BetaSpecificProgrammaticToolCallingParam object { type }` + The type of the input item. Always `input_text`. - - `type: "programmatic_tool_calling"` + - `"input_text"` - The tool to call. Always `programmatic_tool_calling`. + - `prompt_cache_breakpoint: optional object { mode }` - - `"programmatic_tool_calling"` + 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. - - `BetaToolChoiceApplyPatch object { type }` + - `mode: "explicit"` - Forces the model to call the apply_patch tool when executing a tool call. + The breakpoint mode. Always `explicit`. - - `type: "apply_patch"` + - `"explicit"` - The tool to call. Always `apply_patch`. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `"apply_patch"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `BetaToolChoiceShell object { type }` + - `detail: "low" or "high" or "auto" or "original"` - Forces the model to call the shell tool when a tool call is required. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `type: "shell"` + - `"low"` - The tool to call. Always `shell`. + - `"high"` - - `"shell"` + - `"auto"` - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + - `"original"` - 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. + - `type: "input_image"` - We support the following categories of tools: + The type of the input item. Always `input_image`. - - **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. + - `"input_image"` - - `Function object { name, parameters, strict, 5 more }` + - `file_id: optional 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 ID of the file to be sent to the model. - - `name: string` + - `image_url: optional string` - The name of the function to call. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `parameters: map[unknown]` + - `prompt_cache_breakpoint: optional object { mode }` - A JSON schema object describing the parameters of the function. + 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. - - `strict: boolean` + - `mode: "explicit"` - Whether strict parameter validation is enforced for this function tool. + The breakpoint mode. Always `explicit`. - - `type: "function"` + - `"explicit"` - The type of the function tool. Always `function`. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `"function"` + 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"` - - `defer_loading: optional boolean` + 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`. - Whether this function is deferred and loaded via tool search. + - `"auto"` - - `description: optional string` + - `"low"` - A description of the function. Used by the model to determine whether or not to call the function. + - `"high"` - - `output_schema: optional map[unknown]` + - `file_data: optional string` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The content of the file to be sent to the model. - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `file_id: 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). + The ID of the file to be sent to the model. - - `type: "file_search"` + - `file_url: optional string` - The type of the file search tool. Always `file_search`. + The URL of the file to be sent to the model. - - `"file_search"` + - `filename: optional string` - - `vector_store_ids: array of string` + The name of the file to be sent to the model. - The IDs of the vector stores to search. + - `prompt_cache_breakpoint: optional object { mode }` - - `filters: optional object { key, type, value } or object { filters, 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. - A filter to apply. + - `mode: "explicit"` - - `ComparisonFilter object { key, type, value }` + The breakpoint mode. Always `explicit`. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"explicit"` - - `key: string` + - `version: optional string` - The key to compare against the value. + Optional version of the prompt template. - - `type: "eq" or "ne" or "gt" or 5 more` +### Beta Response Queued Event - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. +- `BetaResponseQueuedEvent object { response, sequence_number, type, agent }` - - `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 + Emitted when a response is queued and waiting to be processed. - - `"eq"` + - `response: BetaResponse` - - `"ne"` + The full response object that is queued. - - `"gt"` + - `id: string` - - `"gte"` + Unique identifier for this Response. - - `"lt"` + - `created_at: number` - - `"lte"` + Unix timestamp (in seconds) of when this Response was created. - - `"in"` + - `error: BetaResponseError` - - `"nin"` + An error object returned when the model fails to generate a Response. - - `value: string or number or boolean or array of string or number` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 17 more` - The value to compare against the attribute key; supports string, number, or boolean types. + The error code for the response. - - `string` + - `"server_error"` - - `number` + - `"rate_limit_exceeded"` - - `boolean` + - `"invalid_prompt"` - - `array of string or number` + - `"data_residency_mismatch"` - - `string` + - `"bio_policy"` - - `number` + - `"vector_store_timeout"` - - `CompoundFilter object { filters, type }` + - `"invalid_image"` - Combine multiple filters using `and` or `or`. + - `"invalid_image_format"` - - `filters: array of object { key, type, value } or unknown` + - `"invalid_base64_image"` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `"invalid_image_url"` - - `ComparisonFilter object { key, type, value }` + - `"image_too_large"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"image_too_small"` - - `key: string` + - `"image_parse_error"` - The key to compare against the value. + - `"image_content_policy_violation"` - - `type: "eq" or "ne" or "gt" or 5 more` + - `"invalid_image_mode"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"image_file_too_large"` - - `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 + - `"unsupported_image_media_type"` - - `"eq"` + - `"empty_image_file"` - - `"ne"` + - `"failed_to_download_image"` - - `"gt"` + - `"image_file_not_found"` - - `"gte"` + - `message: string` - - `"lt"` + A human-readable description of the error. - - `"lte"` + - `incomplete_details: object { reason }` - - `"in"` + Details about why the response is incomplete. - - `"nin"` + - `reason: optional "max_output_tokens" or "content_filter"` - - `value: string or number or boolean or array of string or number` + The reason why the response is incomplete. - The value to compare against the attribute key; supports string, number, or boolean types. + - `"max_output_tokens"` - - `string` + - `"content_filter"` - - `number` + - `instructions: string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - - `boolean` + A system (or developer) message inserted into the model's context. - - `array of string or number` + 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` - - `number` + A text input to the model, equivalent to a text input with the + `developer` role. - - `unknown` + - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - - `type: "and" or "or"` + A list of one or many input items to the model, containing + different content types. - Type of operation: `and` or `or`. + - `BetaEasyInputMessage object { content, role, phase, type }` - - `"and"` + 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. - - `"or"` + - `content: string or BetaResponseInputMessageContentList` - - `max_num_results: optional number` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `TextInput = string` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + A text input to the model. - Ranking options for search. + - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` - - `hybrid_search: optional object { embedding_weight, text_weight }` + A list of one or many input items to the model, containing different content + types. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `embedding_weight: number` + A text input to the model. - The weight of the embedding in the reciprocal ranking fusion. + - `text: string` - - `text_weight: number` + The text input to the model. - The weight of the text in the reciprocal ranking fusion. + - `type: "input_text"` - - `ranker: optional "auto" or "default-2024-11-15"` + The type of the input item. Always `input_text`. - The ranker to use for the file search. + - `"input_text"` - - `"auto"` + - `prompt_cache_breakpoint: optional object { mode }` - - `"default-2024-11-15"` + 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. - - `score_threshold: optional number` + - `mode: "explicit"` - 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 breakpoint mode. Always `explicit`. - - `Computer object { type }` + - `"explicit"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `type: "computer"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - The type of the computer tool. Always `computer`. + - `detail: "low" or "high" or "auto" or "original"` - - `"computer"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `"low"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"high"` - - `display_height: number` + - `"auto"` - The height of the computer display. + - `"original"` - - `display_width: number` + - `type: "input_image"` - The width of the computer display. + The type of the input item. Always `input_image`. - - `environment: "windows" or "mac" or "linux" or 2 more` + - `"input_image"` - The type of computer environment to control. + - `file_id: optional string` - - `"windows"` + The ID of the file to be sent to the model. - - `"mac"` + - `image_url: optional string` - - `"linux"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `"ubuntu"` + - `prompt_cache_breakpoint: optional object { mode }` - - `"browser"` + 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_use_preview"` + - `mode: "explicit"` - The type of the computer use tool. Always `computer_use_preview`. + The breakpoint mode. Always `explicit`. - - `"computer_use_preview"` + - `"explicit"` - - `WebSearch object { type, filters, search_context_size, user_location }` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + A file input to the model. - - `type: "web_search" or "web_search_2025_08_26"` + - `type: "input_file"` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + The type of the input item. Always `input_file`. - - `"web_search"` + - `"input_file"` - - `"web_search_2025_08_26"` + - `detail: optional "auto" or "low" or "high"` - - `filters: optional object { allowed_domains }` + 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`. - Filters for the search. + - `"auto"` - - `allowed_domains: optional array of string` + - `"low"` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `"high"` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `file_data: optional string` - - `search_context_size: optional "low" or "medium" or "high"` + The content of the file to be sent 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. + - `file_id: optional string` - - `"low"` + The ID of the file to be sent to the model. - - `"medium"` + - `file_url: optional string` - - `"high"` + The URL of the file to be sent to the model. - - `user_location: optional object { city, country, region, 2 more }` + - `filename: optional string` - The approximate location of the user. + The name of the file to be sent to the model. - - `city: optional string` + - `prompt_cache_breakpoint: optional object { mode }` - Free text input for the city of the user, e.g. `San Francisco`. + 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. - - `country: optional string` + - `mode: "explicit"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The breakpoint mode. Always `explicit`. - - `region: optional string` + - `"explicit"` - Free text input for the region of the user, e.g. `California`. + - `role: "user" or "assistant" or "system" or "developer"` - - `timezone: optional string` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"user"` - - `type: optional "approximate"` + - `"assistant"` - The type of location approximation. Always `approximate`. + - `"system"` - - `"approximate"` + - `"developer"` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `phase: optional "commentary" or "final_answer"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-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. - - `server_label: string` + - `"commentary"` - A label for this MCP server, used to identify it in tool calls. + - `"final_answer"` - - `type: "mcp"` + - `type: optional "message"` - The type of the MCP tool. Always `mcp`. + The type of the message input. Always `message`. - - `"mcp"` + - `"message"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `Message object { content, role, agent, 2 more }` - The tool invocation context(s). + 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. - - `"direct"` + - `content: BetaResponseInputMessageContentList` - - `"programmatic"` + A list of one or many input items to the model, containing different content + types. - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `role: "user" or "system" or "developer"` - List of allowed tool names or a filter object. + The role of the message input. One of `user`, `system`, or `developer`. - - `McpAllowedTools = array of string` + - `"user"` - A string array of allowed tool names + - `"system"` - - `McpToolFilter object { read_only, tool_names }` + - `"developer"` - A filter object to specify which tools are allowed. + - `agent: optional object { agent_name }` - - `read_only: optional boolean` + The agent that produced this item. - 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. + - `agent_name: string` - - `tool_names: optional array of string` + The canonical name of the agent that produced this item. - List of allowed tool names. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `authorization: optional string` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are 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. + - `"in_progress"` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `"completed"` - 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). + - `"incomplete"` - Currently supported `connector_id` values are: + - `type: optional "message"` - - 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 message input. Always set to `message`. - - `"connector_dropbox"` + - `"message"` - - `"connector_gmail"` + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - - `"connector_googlecalendar"` + An output message from the model. - - `"connector_googledrive"` + - `id: string` - - `"connector_microsoftteams"` + The unique ID of the output message. - - `"connector_outlookcalendar"` + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - - `"connector_outlookemail"` + The content of the output message. - - `"connector_sharepoint"` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - - `defer_loading: optional boolean` + A text output from the model. - Whether this MCP tool is deferred and discovered via tool search. + - `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 }` - - `headers: optional map[string]` + The annotations of the text output. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `FileCitation object { file_id, filename, index, type }` - - `require_approval: optional object { always, never } or "always" or "never"` + A citation to a file. - Specify which of the MCP server's tools require approval. + - `file_id: string` - - `McpToolApprovalFilter object { always, never }` + The ID of the 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. + - `filename: string` - - `always: optional object { read_only, tool_names }` + The filename of the file cited. - A filter object to specify which tools are allowed. + - `index: number` - - `read_only: optional boolean` + The index of the file in the list of 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. + - `type: "file_citation"` - - `tool_names: optional array of string` + The type of the file citation. Always `file_citation`. - List of allowed tool names. + - `"file_citation"` - - `never: optional object { read_only, tool_names }` + - `URLCitation object { end_index, start_index, title, 2 more }` - A filter object to specify which tools are allowed. + A citation for a web resource used to generate a model response. - - `read_only: optional boolean` + - `end_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 last character of the URL citation in the message. - - `tool_names: optional array of string` + - `start_index: number` - List of allowed tool names. + The index of the first character of the URL citation in the message. - - `McpToolApprovalSetting = "always" or "never"` + - `title: 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. + The title of the web resource. - - `"always"` + - `type: "url_citation"` - - `"never"` + The type of the URL citation. Always `url_citation`. - - `server_description: optional string` + - `"url_citation"` - Optional description of the MCP server, used to provide more context. + - `url: string` - - `server_url: optional string` + The URL of the web resource. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - - `tunnel_id: optional string` + A citation for a container file used to generate a model response. - 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. + - `container_id: string` - - `CodeInterpreter object { container, type, allowed_callers }` + The ID of the container file. - A tool that runs Python code to help generate a response to a prompt. + - `end_index: number` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + The index of the last character of the container file citation in the message. - 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. + - `file_id: string` - - `string` + The ID of the file. - The container ID. + - `filename: string` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + The filename of the container file cited. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `start_index: number` - - `type: "auto"` + The index of the first character of the container file citation in the message. - Always `auto`. + - `type: "container_file_citation"` - - `"auto"` + The type of the container file citation. Always `container_file_citation`. - - `file_ids: optional array of string` + - `"container_file_citation"` - An optional list of uploaded files to make available to your code. + - `FilePath object { file_id, index, type }` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + A path to a file. - The memory limit for the code interpreter container. + - `file_id: string` - - `"1g"` + The ID of the file. - - `"4g"` + - `index: number` - - `"16g"` + The index of the file in the list of files. - - `"64g"` + - `type: "file_path"` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + The type of the file path. Always `file_path`. - Network access policy for the container. + - `"file_path"` - - `BetaContainerNetworkPolicyDisabled object { type }` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `token: string` - - `type: "code_interpreter"` + - `bytes: array of number` - The type of the code interpreter tool. Always `code_interpreter`. + - `logprob: number` - - `"code_interpreter"` + - `top_logprobs: array of object { token, bytes, logprob }` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `token: string` - The tool invocation context(s). + - `bytes: array of number` - - `"direct"` + - `logprob: number` - - `"programmatic"` + - `text: string` - - `ProgrammaticToolCalling object { type }` + The text output from the model. - - `type: "programmatic_tool_calling"` + - `type: "output_text"` - The type of the tool. Always `programmatic_tool_calling`. + The type of the output text. Always `output_text`. - - `"programmatic_tool_calling"` + - `"output_text"` - - `ImageGeneration object { type, action, background, 9 more }` + - `BetaResponseOutputRefusal object { refusal, type }` - A tool that generates images using the GPT image models. + A refusal from the model. - - `type: "image_generation"` + - `refusal: string` - The type of the image generation tool. Always `image_generation`. + The refusal explanation from the model. - - `"image_generation"` + - `type: "refusal"` - - `action: optional "generate" or "edit" or "auto"` + The type of the refusal. Always `refusal`. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `"refusal"` - - `"generate"` + - `role: "assistant"` - - `"edit"` + The role of the output message. Always `assistant`. - - `"auto"` + - `"assistant"` - - `background: optional "transparent" or "opaque" or "auto"` + - `status: "in_progress" or "completed" or "incomplete"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `"transparent"` + - `"in_progress"` - - `"opaque"` + - `"completed"` - - `"auto"` + - `"incomplete"` - - `input_fidelity: optional "high" or "low"` + - `type: "message"` - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + The type of the output message. Always `message`. - - `"high"` + - `"message"` - - `"low"` + - `agent: optional object { agent_name }` - - `input_image_mask: optional object { file_id, image_url }` + The agent that produced this item. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `agent_name: string` - - `file_id: optional string` + The canonical name of the agent that produced this item. - File ID for the mask image. + - `phase: optional "commentary" or "final_answer"` - - `image_url: optional string` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - Base64-encoded mask image. + - `"commentary"` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"final_answer"` - The image generation model to use. Default: `gpt-image-1`. + - `FileSearchCall object { id, queries, status, 3 more }` - - `string` + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - - `"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. - - `"gpt-image-1"` + - `queries: array of string` - - `"gpt-image-1-mini"` + The queries used to search for files. - - `"gpt-image-1.5"` + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `moderation: optional "auto" or "low"` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - Moderation level for the generated image. Default: `auto`. + - `"in_progress"` - - `"auto"` + - `"searching"` - - `"low"` + - `"completed"` - - `output_compression: optional number` + - `"incomplete"` - Compression level for the output image. Default: 100. + - `"failed"` - - `output_format: optional "png" or "webp" or "jpeg"` + - `type: "file_search_call"` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + The type of the file search tool call. Always `file_search_call`. - - `"png"` + - `"file_search_call"` - - `"webp"` + - `agent: optional object { agent_name }` - - `"jpeg"` + The agent that produced this item. - - `partial_images: optional number` + - `agent_name: string` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The canonical name of the agent that produced this item. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The results of the file search tool call. - - `"low"` + - `attributes: optional map[string or number or boolean]` - - `"medium"` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. Keys are strings + with a maximum length of 64 characters. Values are strings with a maximum + length of 512 characters, booleans, or numbers. - - `"high"` + - `string` - - `"auto"` + - `number` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `boolean` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `file_id: optional string` - - `string` + The unique ID of the file. - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `filename: 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 name of the file. - - `"1024x1024"` + - `score: optional number` - - `"1024x1536"` + The relevance score of the file - a value between 0 and 1. - - `"1536x1024"` + - `text: optional string` - - `"auto"` + The text that was retrieved from the file. - - `LocalShell object { type }` + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - A tool that allows the model to execute shell commands in a local environment. + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - - `type: "local_shell"` + - `id: string` - The type of the local shell tool. Always `local_shell`. + The unique ID of the computer call. - - `"local_shell"` + - `call_id: string` - - `Shell object { type, allowed_callers, environment }` + An identifier used when responding to the tool call with output. - A tool that allows the model to execute shell commands. + - `pending_safety_checks: array of object { id, code, message }` - - `type: "shell"` + The pending safety checks for the computer call. - The type of the shell tool. Always `shell`. + - `id: string` - - `"shell"` + 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. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `status: "in_progress" or "completed" or "incomplete"` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `BetaLocalEnvironment object { type, skills }` + - `"in_progress"` - - `BetaContainerReference 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: "computer_call"` - - `name: string` + The type of the computer call. Always `computer_call`. - The name of the custom tool, used to identify it in tool calls. + - `"computer_call"` - - `type: "custom"` + - `action: optional BetaComputerAction` - The type of the custom tool. Always `custom`. + A click action. - - `"custom"` + - `Click object { button, type, x, 2 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + A click action. - The tool invocation context(s). + - `button: "left" or "right" or "wheel" or 2 more` - - `"direct"` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `"programmatic"` + - `"left"` - - `defer_loading: optional boolean` + - `"right"` - Whether this tool should be deferred and discovered via tool search. + - `"wheel"` - - `description: optional string` + - `"back"` - Optional description of the custom tool, used to provide more context. + - `"forward"` - - `format: optional object { type } or object { definition, syntax, type }` + - `type: "click"` - The input format for the custom tool. Default is unconstrained text. + Specifies the event type. For a click action, this property is always `click`. - - `Text object { type }` + - `"click"` - Unconstrained free-form text. + - `x: number` - - `type: "text"` + The x-coordinate where the click occurred. - Unconstrained text format. Always `text`. + - `y: number` - - `"text"` + The y-coordinate where the click occurred. - - `Grammar object { definition, syntax, type }` + - `keys: optional array of string` - A grammar defined by the user. + The keys being held while clicking. - - `definition: string` + - `DoubleClick object { keys, type, x, y }` - The grammar definition. + A double click action. - - `syntax: "lark" or "regex"` + - `keys: array of string` - The syntax of the grammar definition. One of `lark` or `regex`. + The keys being held while double-clicking. - - `"lark"` + - `type: "double_click"` - - `"regex"` + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `type: "grammar"` + - `"double_click"` - Grammar format. Always `grammar`. + - `x: number` - - `"grammar"` + The x-coordinate where the double click occurred. - - `Namespace object { description, name, tools, type }` + - `y: number` - Groups function/custom tools under a shared namespace. + The y-coordinate where the double click occurred. - - `description: string` + - `Drag object { path, type, keys }` - A description of the namespace shown to the model. + A drag action. - - `name: string` + - `path: array of object { x, y }` - The namespace name used in tool calls (for example, `crm`). + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - The function/custom tools available inside this namespace. + - `x: number` - - `Function object { name, type, allowed_callers, 5 more }` + The x-coordinate. - - `name: string` + - `y: number` - - `type: "function"` + The y-coordinate. - - `"function"` + - `type: "drag"` - - `allowed_callers: optional array of "direct" or "programmatic"` + Specifies the event type. For a drag action, this property is always set to `drag`. - The tool invocation context(s). + - `"drag"` - - `"direct"` + - `keys: optional array of string` - - `"programmatic"` + The keys being held while dragging the mouse. - - `defer_loading: optional boolean` + - `Keypress object { keys, type }` - Whether this function should be deferred and discovered via tool search. + A collection of keypresses the model would like to perform. - - `description: optional string` + - `keys: array of string` - - `output_schema: optional map[unknown]` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `type: "keypress"` - - `parameters: optional unknown` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `strict: optional boolean` + - `"keypress"` - 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. + - `Move object { type, x, y, keys }` - - `Custom object { name, type, allowed_callers, 3 more }` + A mouse move action. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `type: "move"` - - `name: string` + Specifies the event type. For a move action, this property is always set to `move`. - The name of the custom tool, used to identify it in tool calls. + - `"move"` - - `type: "custom"` + - `x: number` - The type of the custom tool. Always `custom`. + The x-coordinate to move to. - - `"custom"` + - `y: number` - - `allowed_callers: optional array of "direct" or "programmatic"` + The y-coordinate to move to. - The tool invocation context(s). + - `keys: optional array of string` - - `"direct"` + The keys being held while moving the mouse. - - `"programmatic"` + - `Screenshot object { type }` - - `defer_loading: optional boolean` + A screenshot action. - Whether this tool should be deferred and discovered via tool search. + - `type: "screenshot"` - - `description: optional string` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - Optional description of the custom tool, used to provide more context. + - `"screenshot"` - - `format: optional object { type } or object { definition, syntax, type }` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - The input format for the custom tool. Default is unconstrained text. + A scroll action. - - `Text object { type }` + - `scroll_x: number` - Unconstrained free-form text. + The horizontal scroll distance. - - `type: "text"` + - `scroll_y: number` - Unconstrained text format. Always `text`. + The vertical scroll distance. - - `"text"` + - `type: "scroll"` - - `Grammar object { definition, syntax, type }` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - A grammar defined by the user. + - `"scroll"` - - `definition: string` + - `x: number` - The grammar definition. + The x-coordinate where the scroll occurred. - - `syntax: "lark" or "regex"` + - `y: number` - The syntax of the grammar definition. One of `lark` or `regex`. + The y-coordinate where the scroll occurred. - - `"lark"` + - `keys: optional array of string` - - `"regex"` + The keys being held while scrolling. - - `type: "grammar"` + - `Type object { text, type }` - Grammar format. Always `grammar`. + An action to type in text. - - `"grammar"` + - `text: string` - - `type: "namespace"` + The text to type. - The type of the tool. Always `namespace`. + - `type: "type"` + + Specifies the event type. For a type action, this property is always set to `type`. - - `"namespace"` + - `"type"` - - `ToolSearch object { type, description, execution, parameters }` + - `Wait object { type }` - Hosted or BYOT tool search configuration for deferred tools. + A wait action. - - `type: "tool_search"` + - `type: "wait"` - The type of the tool. Always `tool_search`. + Specifies the event type. For a wait action, this property is always set to `wait`. - - `"tool_search"` + - `"wait"` - - `description: optional string` + - `actions: optional BetaComputerActionList` - Description shown to the model for a client-executed tool search tool. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `execution: optional "server" or "client"` + - `Click object { button, type, x, 2 more }` - Whether tool search is executed by the server or by the client. + A click action. - - `"server"` + - `DoubleClick object { keys, type, x, y }` - - `"client"` + A double click action. - - `parameters: optional unknown` + - `Drag object { path, type, keys }` - Parameter schema for a client-executed tool search tool. + A drag action. - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `Keypress object { keys, type }` - This tool searches the web for relevant results to use in a response. Learn more about the [web search tool](https://platform.openai.com/docs/guides/tools-web-search). + A collection of keypresses the model would like to perform. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `Move object { type, x, y, keys }` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + A mouse move action. - - `"web_search_preview"` + - `Screenshot object { type }` - - `"web_search_preview_2025_03_11"` + A screenshot action. - - `search_content_types: optional array of "text" or "image"` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `"text"` + A scroll action. - - `"image"` + - `Type object { text, type }` - - `search_context_size: optional "low" or "medium" or "high"` + An action to type in text. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `Wait object { type }` - - `"low"` + A wait action. - - `"medium"` + - `agent: optional object { agent_name }` - - `"high"` + The agent that produced this item. - - `user_location: optional object { type, city, country, 2 more }` + - `agent_name: string` - The user's location. + The canonical name of the agent that produced this item. - - `type: "approximate"` + - `ComputerCallOutput object { call_id, output, type, 4 more }` - The type of location approximation. Always `approximate`. + The output of a computer tool call. - - `"approximate"` + - `call_id: string` - - `city: optional string` + The ID of the computer tool call that produced the output. - Free text input for the city of the user, e.g. `San Francisco`. + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `country: optional string` + A computer screenshot image used with the computer use tool. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `type: "computer_screenshot"` - - `region: optional string` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - Free text input for the region of the user, e.g. `California`. + - `"computer_screenshot"` - - `timezone: optional string` + - `file_id: optional string` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The identifier of an uploaded file that contains the screenshot. - - `ApplyPatch object { type, allowed_callers }` + - `image_url: optional string` - Allows the assistant to create, delete, or update files using unified diffs. + The URL of the screenshot image. - - `type: "apply_patch"` + - `type: "computer_call_output"` - The type of the tool. Always `apply_patch`. + The type of the computer tool call output. Always `computer_call_output`. - - `"apply_patch"` + - `"computer_call_output"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `id: optional string` - The tool invocation context(s). + The ID of the computer tool call output. - - `"direct"` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `"programmatic"` + The safety checks reported by the API that have been acknowledged by the developer. - - `top_p: number` + - `id: string` - 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 ID of the pending safety check. - We generally recommend altering this or `temperature` but not both. + - `code: optional string` - - `background: optional boolean` + The type of the pending safety check. - Whether to run the model response in the background. - [Learn more](/docs/guides/background). + - `message: optional string` - - `completed_at: optional number` + Details about the pending safety check. - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + - `agent: optional object { agent_name }` - - `conversation: optional object { id }` + The agent that produced this item. - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + - `agent_name: string` - - `id: string` + The canonical name of the agent that produced this item. - The unique ID of the conversation that this response was associated with. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `max_output_tokens: optional number` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - 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). + - `"in_progress"` - - `max_tool_calls: optional number` + - `"completed"` - 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. + - `"incomplete"` - - `moderation: optional object { input, output }` + - `WebSearchCall object { id, action, status, 2 more }` - Moderation results for the response input and output, if moderated completions were requested. + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + - `id: string` - Moderation for the response input. + The unique ID of the web search tool call. - - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - A moderation result produced for the response input or output. + 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). - - `categories: map[boolean]` + - `Search object { type, queries, query, sources }` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + Action type "search" - Performs a web search query. - - `category_applied_input_types: map[array of "text" or "image"]` + - `type: "search"` - Which modalities of input are reflected by the score for each category. + The action type. - - `"text"` + - `"search"` - - `"image"` + - `queries: optional array of string` - - `category_scores: map[number]` + The search queries. - A dictionary of moderation categories to scores. + - `query: optional string` - - `flagged: boolean` + The search query. - A boolean indicating whether the content was flagged by any category. + - `sources: optional array of object { type, url }` - - `model: string` + The sources used in the search. - The moderation model that produced this result. + - `type: "url"` - - `type: "moderation_result"` + The type of source. Always `url`. - The object type, which was always `moderation_result` for successful moderation results. + - `"url"` - - `"moderation_result"` + - `url: string` - - `Error object { code, message, type }` + The URL of the source. - An error produced while attempting moderation for the response input or output. + - `OpenPage object { type, url }` - - `code: string` + Action type "open_page" - Opens a specific URL from search results. - The error code. + - `type: "open_page"` - - `message: string` + The action type. - The error message. + - `"open_page"` - - `type: "error"` + - `url: optional string` - The object type, which was always `error` for moderation failures. + The URL opened by the model. - - `"error"` + - `FindInPage object { pattern, type, url }` - - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + Action type "find_in_page": Searches for a pattern within a loaded page. - Moderation for the response output. + - `pattern: string` - - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + The pattern or text to search for within the page. - A moderation result produced for the response input or output. + - `type: "find_in_page"` - - `categories: map[boolean]` + The action type. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `"find_in_page"` - - `category_applied_input_types: map[array of "text" or "image"]` + - `url: string` - Which modalities of input are reflected by the score for each category. + The URL of the page searched for the pattern. - - `"text"` + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `"image"` + The status of the web search tool call. - - `category_scores: map[number]` + - `"in_progress"` - A dictionary of moderation categories to scores. + - `"searching"` - - `flagged: boolean` + - `"completed"` - A boolean indicating whether the content was flagged by any category. + - `"failed"` - - `model: string` + - `type: "web_search_call"` - The moderation model that produced this result. + The type of the web search tool call. Always `web_search_call`. - - `type: "moderation_result"` + - `"web_search_call"` - The object type, which was always `moderation_result` for successful moderation results. + - `agent: optional object { agent_name }` - - `"moderation_result"` + The agent that produced this item. - - `Error object { code, message, type }` + - `agent_name: string` - An error produced while attempting moderation for the response input or output. + The canonical name of the agent that produced this item. - - `code: string` + - `FunctionCall object { arguments, call_id, name, 6 more }` - The error code. + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `message: string` + - `arguments: string` - The error message. + A JSON string of the arguments to pass to the function. - - `type: "error"` + - `call_id: string` - The object type, which was always `error` for moderation failures. + The unique ID of the function tool call generated by the model. - - `"error"` + - `name: string` - - `output_text: optional string` + The name of the function to run. - 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. + - `type: "function_call"` - - `previous_response_id: optional string` + The type of the function tool call. Always `function_call`. - 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`. + - `"function_call"` - - `prompt: optional BetaResponsePrompt` + - `id: optional string` - Reference to a prompt template and its variables. - [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). + The unique ID of the function tool call. - - `id: string` + - `agent: optional object { agent_name }` - The unique identifier of the prompt template to use. + The agent that produced this item. - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + - `agent_name: 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 canonical name of the agent that produced this item. - - `string` + - `caller: optional object { type } or object { caller_id, type }` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + The execution context that produced this tool call. - A text input to the model. + - `Direct object { type }` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `type: "direct"` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `"direct"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `Program object { caller_id, type }` - A file input to the model. + - `caller_id: string` - - `version: optional string` + The call ID of the program item that produced this tool call. - Optional version of the prompt template. + - `type: "program"` - - `prompt_cache_key: optional string` + - `"program"` - 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). + - `namespace: optional string` - - `prompt_cache_options: optional object { mode, ttl }` + The namespace of the function to run. - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `mode: "implicit" or "explicit"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Whether implicit prompt-cache breakpoints were enabled. + - `"in_progress"` - - `"implicit"` + - `"completed"` - - `"explicit"` + - `"incomplete"` - - `ttl: "30m"` + - `FunctionCallOutput object { call_id, output, type, 4 more }` - The minimum lifetime applied to each cache breakpoint. + The output of a function tool call. - - `"30m"` + - `call_id: string` - - `prompt_cache_retention: optional "in_memory" or "24h"` + The unique ID of the function tool call generated by the model. - Deprecated. Use `prompt_cache_options.ttl` instead. + - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - 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. + Text, image, or file output of the function tool call. - 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. + A JSON string of the output of the function tool call. - - `"in_memory"` + - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - - `"24h"` + An array of content outputs (text, image, file) for the function tool call. - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - **gpt-5 and o-series models only** + A text input to the model. - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `text: string` - - `context: optional "auto" or "current_turn" or "all_turns"` + The text input to the model. - 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`. + - `type: "input_text"` - When returned on a response, this is the effective reasoning context mode - used for the response. + The type of the input item. Always `input_text`. - - `"auto"` + - `"input_text"` - - `"current_turn"` + - `prompt_cache_breakpoint: optional object { mode }` - - `"all_turns"` + 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. - - `effort: optional "none" or "minimal" or "low" or 4 more` + - `mode: "explicit"` - 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 breakpoint mode. Always `explicit`. - - `"none"` + - `"explicit"` - - `"minimal"` + - `BetaResponseInputImageContent 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`. - - `"xhigh"` + - `"input_image"` - - `"max"` + - `detail: optional "low" or "high" or "auto" or "original"` - - `generate_summary: optional "auto" or "concise" or "detailed"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - **Deprecated:** use `summary` instead. + - `"low"` - 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`. + - `"high"` - `"auto"` - - `"concise"` + - `"original"` - - `"detailed"` + - `file_id: optional string` - - `mode: optional string or "standard" or "pro"` + The ID of the file to be sent to the model. - Controls the reasoning execution mode for the request. + - `image_url: optional string` - When returned on a response, this is the effective execution mode. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `string` + - `prompt_cache_breakpoint: optional object { mode }` - - `"standard" or "pro"` + 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. - Controls the reasoning execution mode for the request. + - `mode: "explicit"` - When returned on a response, this is the effective execution mode. + The breakpoint mode. Always `explicit`. - - `"standard"` + - `"explicit"` - - `"pro"` + - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` - - `summary: optional "auto" or "concise" or "detailed"` + A file input to the model. - 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: "input_file"` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + The type of the input item. Always `input_file`. - - `"auto"` + - `"input_file"` - - `"concise"` + - `detail: optional "auto" or "low" or "high"` - - `"detailed"` + 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`. - - `safety_identifier: optional string` + - `"auto"` - 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). + - `"low"` - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + - `"high"` - Specifies the processing type used for serving the request. + - `file_data: optional string` - - 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 base64-encoded data of the file to be sent to the model. - 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. + - `file_id: optional string` - - `"auto"` + The ID of the file to be sent to the model. - - `"default"` + - `file_url: optional string` - - `"flex"` + The URL of the file to be sent to the model. - - `"scale"` + - `filename: optional string` - - `"priority"` + The name of the file to be sent to the model. - - `status: optional BetaResponseStatus` + - `prompt_cache_breakpoint: optional object { mode }` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, 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. - - `"completed"` + - `mode: "explicit"` - - `"failed"` + The breakpoint mode. Always `explicit`. - - `"in_progress"` + - `"explicit"` - - `"cancelled"` + - `type: "function_call_output"` - - `"queued"` + The type of the function tool call output. Always `function_call_output`. - - `"incomplete"` + - `"function_call_output"` - - `text: optional BetaResponseTextConfig` + - `id: optional string` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + The unique ID of the function tool call output. Populated when this item is returned via API. - - [Text inputs and outputs](/docs/guides/text) - - [Structured Outputs](/docs/guides/structured-outputs) + - `agent: optional object { agent_name }` - - `format: optional BetaResponseFormatTextConfig` + The agent that produced this item. - An object specifying the format that the model must output. + - `agent_name: 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 canonical name of the agent that produced this item. - The default format is `{ "type": "text" }` with no additional options. + - `caller: optional object { type } or object { caller_id, type }` - **Not recommended for gpt-4o and newer models:** + The execution context that produced this tool call. - 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. + - `Direct object { type }` - - `Text object { type }` + - `type: "direct"` - Default response format. Used to generate text responses. + The caller type. Always `direct`. - - `type: "text"` + - `"direct"` - The type of response format being defined. Always `text`. + - `Program object { caller_id, type }` - - `"text"` + - `caller_id: string` - - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` + The call ID of the program item that produced this tool call. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + - `type: "program"` - - `name: string` + The caller type. Always `program`. - 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. + - `"program"` - - `schema: map[unknown]` + - `status: optional "in_progress" or "completed" or "incomplete"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `type: "json_schema"` + - `"in_progress"` - The type of response format being defined. Always `json_schema`. + - `"completed"` - - `"json_schema"` + - `"incomplete"` - - `description: optional string` + - `AgentMessage object { author, content, recipient, 3 more }` - A description of what the response format is for, used by the model to - determine how to respond in the format. + A message routed between agents. - - `strict: optional boolean` + - `author: 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 sending agent identity. - - `JSONObject object { type }` + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, 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. + Plaintext, image, or encrypted content sent between agents. - - `type: "json_object"` + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - The type of response format being defined. Always `json_object`. + A text input to the model. - - `"json_object"` + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - - `verbosity: optional "low" or "medium" or "high"` + An image input to the model. Learn about [image inputs](/docs/guides/vision) - 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`. + - `EncryptedContent object { encrypted_content, type }` - - `"low"` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `"medium"` + - `encrypted_content: string` - - `"high"` + Opaque encrypted content. - - `top_logprobs: optional number` + - `type: "encrypted_content"` - 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. + The type of the input item. Always `encrypted_content`. - - `truncation: optional "auto" or "disabled"` + - `"encrypted_content"` - The truncation strategy to use for the model response. + - `recipient: 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. + The destination agent identity. - - `"auto"` + - `type: "agent_message"` - - `"disabled"` + The item type. Always `agent_message`. - - `usage: optional BetaResponseUsage` + - `"agent_message"` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `id: optional string` - - `input_tokens: number` + The unique ID of this agent message item. - The number of input tokens. + - `agent: optional object { agent_name }` - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + The agent that produced this item. - A detailed breakdown of the input tokens. + - `agent_name: string` - - `cache_write_tokens: number` + The canonical name of the agent that produced this item. - The number of input tokens that were written to the cache. + - `MultiAgentCall object { action, arguments, call_id, 3 more }` - - `cached_tokens: number` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - The number of tokens that were retrieved from the cache. - [More on prompt caching](/docs/guides/prompt-caching). + The multi-agent action that was executed. - - `output_tokens: number` + - `"spawn_agent"` - The number of output tokens. + - `"interrupt_agent"` - - `output_tokens_details: object { reasoning_tokens }` + - `"list_agents"` - A detailed breakdown of the output tokens. + - `"send_message"` - - `reasoning_tokens: number` + - `"followup_task"` - The number of reasoning tokens. + - `"wait_agent"` - - `total_tokens: number` + - `arguments: string` - The total number of tokens used. + The action arguments as a JSON string. - - `user: optional string` + - `call_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 linking this call to its output. - - `sequence_number: number` + - `type: "multi_agent_call"` - The sequence number for this event. + The item type. Always `multi_agent_call`. - - `type: "response.queued"` + - `"multi_agent_call"` - The type of the event. Always 'response.queued'. + - `id: optional string` - - `"response.queued"` + The unique ID of this multi-agent call. - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. -### Beta Response Reasoning Summary Part Added Event + - `MultiAgentCallOutput object { action, call_id, output, 3 more }` -- `BetaResponseReasoningSummaryPartAddedEvent object { item_id, output_index, part, 4 more }` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - Emitted when a new reasoning summary part is added. + The multi-agent action that produced this result. - - `item_id: string` + - `"spawn_agent"` - The ID of the item this summary part is associated with. + - `"interrupt_agent"` - - `output_index: number` + - `"list_agents"` - The index of the output item this summary part is associated with. + - `"send_message"` - - `part: object { text, type }` + - `"followup_task"` - The summary part that was added. + - `"wait_agent"` + + - `call_id: string` + + The unique ID of the multi-agent call. + + - `output: array of object { text, type, annotations }` + + Text output returned by the multi-agent action. - `text: string` - The text of the summary part. + The text content. - - `type: "summary_text"` + - `type: "output_text"` - The type of the summary part. Always `summary_text`. + The content type. Always `output_text`. - - `"summary_text"` + - `"output_text"` - - `sequence_number: number` + - `annotations: optional 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 }` - The sequence number of this event. + Citations associated with the text content. - - `summary_index: number` + - `FileCitation object { file_id, filename, index, type }` - The index of the summary part within the reasoning summary. + - `file_id: string` - - `type: "response.reasoning_summary_part.added"` + The ID of the file. - The type of the event. Always `response.reasoning_summary_part.added`. + - `filename: string` - - `"response.reasoning_summary_part.added"` + The filename of the file cited. - - `agent: optional object { agent_name }` + - `index: number` - The agent that owns this multi-agent streaming event. + The index of the file in the list of files. - - `agent_name: string` + - `type: "file_citation"` - The canonical name of the agent that produced this item. + The citation type. Always `file_citation`. -### Beta Response Reasoning Summary Part Done Event + - `"file_citation"` -- `BetaResponseReasoningSummaryPartDoneEvent object { item_id, output_index, part, 5 more }` + - `URLCitation object { end_index, start_index, title, 2 more }` - Emitted when a reasoning summary part is completed. + - `end_index: number` - - `item_id: string` + The index of the last character of the citation in the message. - The ID of the item this summary part is associated with. + - `start_index: number` - - `output_index: number` + The index of the first character of the citation in the message. - The index of the output item this summary part is associated with. + - `title: string` - - `part: object { text, type }` + The title of the cited resource. - The completed summary part. + - `type: "url_citation"` - - `text: string` + The citation type. Always `url_citation`. - The text of the summary part. + - `"url_citation"` - - `type: "summary_text"` + - `url: string` - The type of the summary part. Always `summary_text`. + The URL of the cited resource. - - `"summary_text"` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - - `sequence_number: number` + - `container_id: string` - The sequence number of this event. + The ID of the container. - - `summary_index: number` + - `end_index: number` - The index of the summary part within the reasoning summary. + The index of the last character of the citation in the message. - - `type: "response.reasoning_summary_part.done"` + - `file_id: string` - The type of the event. Always `response.reasoning_summary_part.done`. + The ID of the container file. - - `"response.reasoning_summary_part.done"` + - `filename: string` - - `agent: optional object { agent_name }` + The filename of the container file cited. - The agent that owns this multi-agent streaming event. + - `start_index: number` - - `agent_name: string` + The index of the first character of the citation in the message. - The canonical name of the agent that produced this item. + - `type: "container_file_citation"` - - `status: optional "incomplete"` + The citation type. Always `container_file_citation`. - The completion status of the summary part. Omitted when the part completed - normally and set to `incomplete` when generation was interrupted. + - `"container_file_citation"` - - `"incomplete"` + - `type: "multi_agent_call_output"` -### Beta Response Reasoning Summary Text Delta Event + The item type. Always `multi_agent_call_output`. -- `BetaResponseReasoningSummaryTextDeltaEvent object { delta, item_id, output_index, 4 more }` + - `"multi_agent_call_output"` - Emitted when a delta is added to a reasoning summary text. + - `id: optional string` - - `delta: string` + The unique ID of this multi-agent call output. - The text delta that was added to the summary. + - `agent: optional object { agent_name }` - - `item_id: string` + The agent that produced this item. - The ID of the item this summary text delta is associated with. + - `agent_name: string` - - `output_index: number` + The canonical name of the agent that produced this item. - The index of the output item this summary text delta is associated with. + - `ToolSearchCall object { arguments, type, id, 4 more }` - - `sequence_number: number` + - `arguments: unknown` - The sequence number of this event. + The arguments supplied to the tool search call. - - `summary_index: number` + - `type: "tool_search_call"` - The index of the summary part within the reasoning summary. + The item type. Always `tool_search_call`. - - `type: "response.reasoning_summary_text.delta"` + - `"tool_search_call"` - The type of the event. Always `response.reasoning_summary_text.delta`. + - `id: optional string` - - `"response.reasoning_summary_text.delta"` + The unique ID of this tool search call. - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. -### Beta Response Reasoning Summary Text Done Event + - `call_id: optional string` -- `BetaResponseReasoningSummaryTextDoneEvent object { item_id, output_index, sequence_number, 4 more }` + The unique ID of the tool search call generated by the model. - Emitted when a reasoning summary text is completed. + - `execution: optional "server" or "client"` - - `item_id: string` + Whether tool search was executed by the server or by the client. - The ID of the item this summary text is associated with. + - `"server"` - - `output_index: number` + - `"client"` - The index of the output item this summary text is associated with. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `sequence_number: number` + The status of the tool search call. - The sequence number of this event. + - `"in_progress"` - - `summary_index: number` + - `"completed"` - The index of the summary part within the reasoning summary. + - `"incomplete"` - - `text: string` + - `ToolSearchOutput object { tools, type, id, 4 more }` - The full text of the completed reasoning summary. + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - - `type: "response.reasoning_summary_text.done"` + The loaded tool definitions returned by the tool search output. - The type of the event. Always `response.reasoning_summary_text.done`. + - `Function object { name, parameters, strict, 5 more }` - - `"response.reasoning_summary_text.done"` + 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). - - `agent: optional object { agent_name }` + - `name: string` - The agent that owns this multi-agent streaming event. + The name of the function to call. - - `agent_name: string` + - `parameters: map[unknown]` - The canonical name of the agent that produced this item. + A JSON schema object describing the parameters of the function. -### Beta Response Reasoning Text Delta Event + - `strict: boolean` -- `BetaResponseReasoningTextDeltaEvent object { content_index, delta, item_id, 4 more }` + Whether strict parameter validation is enforced for this function tool. - Emitted when a delta is added to a reasoning text. + - `type: "function"` - - `content_index: number` + The type of the function tool. Always `function`. - The index of the reasoning content part this delta is associated with. + - `"function"` - - `delta: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The text delta that was added to the reasoning content. + The tool invocation context(s). - - `item_id: string` + - `"direct"` - The ID of the item this reasoning text delta is associated with. + - `"programmatic"` - - `output_index: number` + - `defer_loading: optional boolean` - The index of the output item this reasoning text delta is associated with. + Whether this function is deferred and loaded via tool search. - - `sequence_number: number` + - `description: optional string` - The sequence number of this event. + A description of the function. Used by the model to determine whether or not to call the function. - - `type: "response.reasoning_text.delta"` + - `output_schema: optional map[unknown]` - The type of the event. Always `response.reasoning_text.delta`. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `"response.reasoning_text.delta"` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `agent: optional object { agent_name }` + 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 agent that owns this multi-agent streaming event. + - `type: "file_search"` - - `agent_name: string` + The type of the file search tool. Always `file_search`. - The canonical name of the agent that produced this item. + - `"file_search"` -### Beta Response Reasoning Text Done Event + - `vector_store_ids: array of string` -- `BetaResponseReasoningTextDoneEvent object { content_index, item_id, output_index, 4 more }` + The IDs of the vector stores to search. - Emitted when a reasoning text is completed. + - `filters: optional object { key, type, value } or object { filters, type }` - - `content_index: number` + A filter to apply. - The index of the reasoning content part. + - `ComparisonFilter object { key, type, value }` - - `item_id: string` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The ID of the item this reasoning text is associated with. + - `key: string` - - `output_index: number` + The key to compare against the value. - The index of the output item this reasoning text is associated with. + - `type: "eq" or "ne" or "gt" or 5 more` - - `sequence_number: number` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The sequence number of this event. + - `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 - - `text: string` + - `"eq"` - The full text of the completed reasoning content. + - `"ne"` - - `type: "response.reasoning_text.done"` + - `"gt"` - The type of the event. Always `response.reasoning_text.done`. + - `"gte"` - - `"response.reasoning_text.done"` + - `"lt"` - - `agent: optional object { agent_name }` + - `"lte"` - The agent that owns this multi-agent streaming event. + - `"in"` - - `agent_name: string` + - `"nin"` - The canonical name of the agent that produced this item. + - `value: string or number or boolean or array of string or number` -### Beta Response Refusal Delta Event + The value to compare against the attribute key; supports string, number, or boolean types. -- `BetaResponseRefusalDeltaEvent object { content_index, delta, item_id, 4 more }` + - `string` - Emitted when there is a partial refusal text. + - `number` - - `content_index: number` + - `boolean` - The index of the content part that the refusal text is added to. + - `array of string or number` - - `delta: string` + - `string` - The refusal text that is added. + - `number` - - `item_id: string` + - `CompoundFilter object { filters, type }` - The ID of the output item that the refusal text is added to. + Combine multiple filters using `and` or `or`. - - `output_index: number` + - `filters: array of object { key, type, value } or unknown` - The index of the output item that the refusal text is added to. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `sequence_number: number` + - `ComparisonFilter object { key, type, value }` - The sequence number of this event. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `type: "response.refusal.delta"` + - `key: string` - The type of the event. Always `response.refusal.delta`. + The key to compare against the value. - - `"response.refusal.delta"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `agent: optional object { agent_name }` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The agent that owns this multi-agent streaming event. + - `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 - - `agent_name: string` + - `"eq"` - The canonical name of the agent that produced this item. + - `"ne"` -### Beta Response Refusal Done Event + - `"gt"` -- `BetaResponseRefusalDoneEvent object { content_index, item_id, output_index, 4 more }` + - `"gte"` - Emitted when refusal text is finalized. + - `"lt"` - - `content_index: number` + - `"lte"` - The index of the content part that the refusal text is finalized. + - `"in"` - - `item_id: string` + - `"nin"` - The ID of the output item that the refusal text is finalized. + - `value: string or number or boolean or array of string or number` - - `output_index: number` + The value to compare against the attribute key; supports string, number, or boolean types. - The index of the output item that the refusal text is finalized. + - `string` - - `refusal: string` + - `number` - The refusal text that is finalized. + - `boolean` - - `sequence_number: number` + - `array of string or number` - The sequence number of this event. + - `string` - - `type: "response.refusal.done"` + - `number` - The type of the event. Always `response.refusal.done`. + - `unknown` - - `"response.refusal.done"` + - `type: "and" or "or"` - - `agent: optional object { agent_name }` + Type of operation: `and` or `or`. - The agent that owns this multi-agent streaming event. + - `"and"` - - `agent_name: string` + - `"or"` - The canonical name of the agent that produced this item. + - `max_num_results: optional number` -### Beta Response Status + The maximum number of results to return. This number should be between 1 and 50 inclusive. -- `BetaResponseStatus = "completed" or "failed" or "in_progress" or 3 more` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + Ranking options for search. - - `"completed"` + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `"failed"` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `"in_progress"` + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. - - `"cancelled"` + - `text_weight: number` - - `"queued"` + The weight of the text in the reciprocal ranking fusion. - - `"incomplete"` + - `ranker: optional "auto" or "default-2024-11-15"` -### Beta Response Stream Event + The ranker to use for the file search. -- `BetaResponseStreamEvent = BetaResponseAudioDeltaEvent or BetaResponseAudioDoneEvent or BetaResponseAudioTranscriptDeltaEvent or 50 more` + - `"auto"` - Emitted when there is a partial audio response. + - `"default-2024-11-15"` - - `BetaResponseAudioDeltaEvent object { delta, sequence_number, type, agent }` + - `score_threshold: optional number` - Emitted when there is a partial audio response. + 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. - - `delta: string` + - `Computer object { type }` - A chunk of Base64 encoded response audio bytes. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `sequence_number: number` + - `type: "computer"` - A sequence number for this chunk of the stream response. + The type of the computer tool. Always `computer`. - - `type: "response.audio.delta"` + - `"computer"` - The type of the event. Always `response.audio.delta`. + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `"response.audio.delta"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `agent: optional object { agent_name }` + - `display_height: number` - The agent that owns this multi-agent streaming event. + The height of the computer display. - - `agent_name: string` + - `display_width: number` - The canonical name of the agent that produced this item. + The width of the computer display. - - `BetaResponseAudioDoneEvent object { sequence_number, type, agent }` + - `environment: "windows" or "mac" or "linux" or 2 more` - Emitted when the audio response is complete. + The type of computer environment to control. - - `sequence_number: number` + - `"windows"` - The sequence number of the delta. + - `"mac"` - - `type: "response.audio.done"` + - `"linux"` - The type of the event. Always `response.audio.done`. + - `"ubuntu"` - - `"response.audio.done"` + - `"browser"` - - `agent: optional object { agent_name }` + - `type: "computer_use_preview"` - The agent that owns this multi-agent streaming event. + The type of the computer use tool. Always `computer_use_preview`. - - `agent_name: string` + - `"computer_use_preview"` - The canonical name of the agent that produced this item. + - `WebSearch object { type, filters, search_context_size, user_location }` - - `BetaResponseAudioTranscriptDeltaEvent object { delta, sequence_number, type, agent }` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - Emitted when there is a partial transcript of audio. + - `type: "web_search" or "web_search_2025_08_26"` - - `delta: string` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - The partial transcript of the audio response. + - `"web_search"` - - `sequence_number: number` + - `"web_search_2025_08_26"` - The sequence number of this event. + - `filters: optional object { allowed_domains }` - - `type: "response.audio.transcript.delta"` + Filters for the search. - The type of the event. Always `response.audio.transcript.delta`. + - `allowed_domains: optional array of string` - - `"response.audio.transcript.delta"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `agent: optional object { agent_name }` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - The agent that owns this multi-agent streaming event. + - `search_context_size: optional "low" or "medium" or "high"` - - `agent_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 canonical name of the agent that produced this item. + - `"low"` - - `BetaResponseAudioTranscriptDoneEvent object { sequence_number, type, agent }` + - `"medium"` - Emitted when the full audio transcript is completed. + - `"high"` - - `sequence_number: number` + - `user_location: optional object { city, country, region, 2 more }` - The sequence number of this event. + The approximate location of the user. - - `type: "response.audio.transcript.done"` + - `city: optional string` - The type of the event. Always `response.audio.transcript.done`. + Free text input for the city of the user, e.g. `San Francisco`. - - `"response.audio.transcript.done"` + - `country: optional string` - - `agent: optional object { agent_name }` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The agent that owns this multi-agent streaming event. + - `region: optional string` - - `agent_name: string` + Free text input for the region of the user, e.g. `California`. - The canonical name of the agent that produced this item. + - `timezone: optional string` - - `BetaResponseCodeInterpreterCallCodeDeltaEvent object { delta, item_id, output_index, 3 more }` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - Emitted when a partial code snippet is streamed by the code interpreter. + - `type: optional "approximate"` - - `delta: string` + The type of location approximation. Always `approximate`. - The partial code snippet being streamed by the code interpreter. + - `"approximate"` - - `item_id: string` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - The unique identifier of the code interpreter tool call item. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `output_index: number` + - `server_label: string` - The index of the output item in the response for which the code is being streamed. + A label for this MCP server, used to identify it in tool calls. - - `sequence_number: number` + - `type: "mcp"` - The sequence number of this event, used to order streaming events. + The type of the MCP tool. Always `mcp`. - - `type: "response.code_interpreter_call_code.delta"` + - `"mcp"` - The type of the event. Always `response.code_interpreter_call_code.delta`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"response.code_interpreter_call_code.delta"` + The tool invocation context(s). - - `agent: optional object { agent_name }` + - `"direct"` - The agent that owns this multi-agent streaming event. + - `"programmatic"` - - `agent_name: string` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - The canonical name of the agent that produced this item. + List of allowed tool names or a filter object. - - `BetaResponseCodeInterpreterCallCodeDoneEvent object { code, item_id, output_index, 3 more }` + - `McpAllowedTools = array of string` - Emitted when the code snippet is finalized by the code interpreter. + A string array of allowed tool names - - `code: string` + - `McpToolFilter object { read_only, tool_names }` - The final code snippet output by the code interpreter. + A filter object to specify which tools are allowed. - - `item_id: string` + - `read_only: optional boolean` - The unique identifier of the code interpreter tool call item. + 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_index: number` + - `tool_names: optional array of string` - The index of the output item in the response for which the code is finalized. + List of allowed tool names. - - `sequence_number: number` + - `authorization: optional string` - The sequence number of this event, used to order streaming events. + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - - `type: "response.code_interpreter_call_code.done"` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - The type of the event. Always `response.code_interpreter_call_code.done`. + 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). - - `"response.code_interpreter_call_code.done"` + Currently supported `connector_id` values are: - - `agent: optional object { agent_name }` + - 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 agent that owns this multi-agent streaming event. + - `"connector_dropbox"` - - `agent_name: string` + - `"connector_gmail"` - The canonical name of the agent that produced this item. + - `"connector_googlecalendar"` - - `BetaResponseCodeInterpreterCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` + - `"connector_googledrive"` - Emitted when the code interpreter call is completed. + - `"connector_microsoftteams"` - - `item_id: string` + - `"connector_outlookcalendar"` - The unique identifier of the code interpreter tool call item. + - `"connector_outlookemail"` - - `output_index: number` + - `"connector_sharepoint"` - The index of the output item in the response for which the code interpreter call is completed. + - `defer_loading: optional boolean` - - `sequence_number: number` + Whether this MCP tool is deferred and discovered via tool search. - The sequence number of this event, used to order streaming events. + - `headers: optional map[string]` - - `type: "response.code_interpreter_call.completed"` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The type of the event. Always `response.code_interpreter_call.completed`. + - `require_approval: optional object { always, never } or "always" or "never"` - - `"response.code_interpreter_call.completed"` + Specify which of the MCP server's tools require approval. - - `agent: optional object { agent_name }` + - `McpToolApprovalFilter object { always, never }` - The agent that owns this multi-agent streaming event. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `agent_name: string` + - `always: optional object { read_only, tool_names }` - The canonical name of the agent that produced this item. + A filter object to specify which tools are allowed. - - `BetaResponseCodeInterpreterCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + - `read_only: optional boolean` - Emitted when a code interpreter call is in progress. + 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. - - `item_id: string` + - `tool_names: optional array of string` - The unique identifier of the code interpreter tool call item. + List of allowed tool names. - - `output_index: number` + - `never: optional object { read_only, tool_names }` - The index of the output item in the response for which the code interpreter call is in progress. + A filter object to specify which tools are allowed. - - `sequence_number: number` + - `read_only: optional boolean` - The sequence number of this event, used to order streaming events. + 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: "response.code_interpreter_call.in_progress"` + - `tool_names: optional array of string` - The type of the event. Always `response.code_interpreter_call.in_progress`. + List of allowed tool names. - - `"response.code_interpreter_call.in_progress"` + - `McpToolApprovalSetting = "always" or "never"` - - `agent: optional object { agent_name }` + 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 agent that owns this multi-agent streaming event. + - `"always"` - - `agent_name: string` + - `"never"` - The canonical name of the agent that produced this item. + - `server_description: optional string` - - `BetaResponseCodeInterpreterCallInterpretingEvent object { item_id, output_index, sequence_number, 2 more }` + Optional description of the MCP server, used to provide more context. - Emitted when the code interpreter is actively interpreting the code snippet. + - `server_url: optional string` - - `item_id: string` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - The unique identifier of the code interpreter tool call item. + - `tunnel_id: optional string` - - `output_index: number` + 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 index of the output item in the response for which the code interpreter is interpreting code. + - `CodeInterpreter object { container, type, allowed_callers }` - - `sequence_number: number` + A tool that runs Python code to help generate a response to a prompt. - The sequence number of this event, used to order streaming events. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `type: "response.code_interpreter_call.interpreting"` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - The type of the event. Always `response.code_interpreter_call.interpreting`. + - `string` - - `"response.code_interpreter_call.interpreting"` + The container ID. - - `agent: optional object { agent_name }` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - The agent that owns this multi-agent streaming event. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `agent_name: string` + - `type: "auto"` - The canonical name of the agent that produced this item. + Always `auto`. - - `BetaResponseCompletedEvent object { response, sequence_number, type, agent }` + - `"auto"` - Emitted when the model response is complete. + - `file_ids: optional array of string` - - `response: BetaResponse` + An optional list of uploaded files to make available to your code. - Properties of the completed response. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `id: string` + The memory limit for the code interpreter container. - Unique identifier for this Response. + - `"1g"` - - `created_at: number` + - `"4g"` - Unix timestamp (in seconds) of when this Response was created. + - `"16g"` - - `error: BetaResponseError` + - `"64g"` - An error object returned when the model fails to generate a Response. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 17 more` + Network access policy for the container. - The error code for the response. + - `BetaContainerNetworkPolicyDisabled object { type }` - - `"server_error"` + - `type: "disabled"` - - `"rate_limit_exceeded"` + Disable outbound network access. Always `disabled`. - - `"invalid_prompt"` + - `"disabled"` - - `"data_residency_mismatch"` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `"bio_policy"` + - `allowed_domains: array of string` - - `"vector_store_timeout"` + A list of allowed domains when type is `allowlist`. - - `"invalid_image"` + - `type: "allowlist"` - - `"invalid_image_format"` + Allow outbound network access only to specified domains. Always `allowlist`. - - `"invalid_base64_image"` + - `"allowlist"` - - `"invalid_image_url"` + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - - `"image_too_large"` + Optional domain-scoped secrets for allowlisted domains. - - `"image_too_small"` + - `domain: string` - - `"image_parse_error"` + The domain associated with the secret. - - `"image_content_policy_violation"` + - `name: string` - - `"invalid_image_mode"` + The name of the secret to inject for the domain. - - `"image_file_too_large"` + - `value: string` - - `"unsupported_image_media_type"` + The secret value to inject for the domain. - - `"empty_image_file"` + - `type: "code_interpreter"` - - `"failed_to_download_image"` + The type of the code interpreter tool. Always `code_interpreter`. - - `"image_file_not_found"` + - `"code_interpreter"` - - `message: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - A human-readable description of the error. + The tool invocation context(s). - - `incomplete_details: object { reason }` + - `"direct"` - Details about why the response is incomplete. + - `"programmatic"` - - `reason: optional "max_output_tokens" or "content_filter"` + - `ProgrammaticToolCalling object { type }` - The reason why the response is incomplete. + - `type: "programmatic_tool_calling"` - - `"max_output_tokens"` + The type of the tool. Always `programmatic_tool_calling`. - - `"content_filter"` + - `"programmatic_tool_calling"` - - `instructions: string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + - `ImageGeneration object { type, action, background, 9 more }` - A system (or developer) message inserted into the model's context. + A tool that generates images using the GPT image models. - 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. + - `type: "image_generation"` - - `string` + The type of the image generation tool. Always `image_generation`. - A text input to the model, equivalent to a text input with the - `developer` role. + - `"image_generation"` - - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + - `action: optional "generate" or "edit" or "auto"` - A list of one or many input items to the model, containing - different content types. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `BetaEasyInputMessage object { content, role, phase, type }` + - `"generate"` - 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. + - `"edit"` - - `content: string or BetaResponseInputMessageContentList` + - `"auto"` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `background: optional "transparent" or "opaque" or "auto"` - - `TextInput = string` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - A text input to the model. + - `"transparent"` - - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` + - `"opaque"` - A list of one or many input items to the model, containing different content - types. + - `"auto"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `input_fidelity: optional "high" or "low"` - A text input to the model. + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `text: string` + - `"high"` - The text input to the model. + - `"low"` - - `type: "input_text"` + - `input_image_mask: optional object { file_id, image_url }` - The type of the input item. Always `input_text`. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `"input_text"` + - `file_id: optional string` - - `prompt_cache_breakpoint: optional object { mode }` + File ID for the mask 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. + - `image_url: optional string` - - `mode: "explicit"` + Base64-encoded mask image. - The breakpoint mode. Always `explicit`. + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `"explicit"` + The image generation model to use. Default: `gpt-image-1`. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `string` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `detail: "low" or "high" or "auto" or "original"` + The image generation model to use. Default: `gpt-image-1`. - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"gpt-image-1"` - - `"low"` + - `"gpt-image-1-mini"` - - `"high"` + - `"gpt-image-1.5"` - - `"auto"` + - `moderation: optional "auto" or "low"` - - `"original"` + Moderation level for the generated image. Default: `auto`. - - `type: "input_image"` + - `"auto"` - The type of the input item. Always `input_image`. + - `"low"` - - `"input_image"` + - `output_compression: optional number` - - `file_id: optional string` + Compression level for the output image. Default: 100. - The ID of the file to be sent to the model. + - `output_format: optional "png" or "webp" or "jpeg"` - - `image_url: optional string` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `"png"` - - `prompt_cache_breakpoint: optional object { mode }` + - `"webp"` - 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. + - `"jpeg"` - - `mode: "explicit"` + - `partial_images: optional number` - The breakpoint mode. Always `explicit`. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `"explicit"` + - `quality: optional "low" or "medium" or "high" or "auto"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - A file input to the model. + - `"low"` - - `type: "input_file"` + - `"medium"` - The type of the input item. Always `input_file`. + - `"high"` - - `"input_file"` + - `"auto"` - - `detail: optional "auto" or "low" or "high"` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - 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 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`. - - `"auto"` + - `string` - - `"low"` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `"high"` + 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`. - - `file_data: optional string` + - `"1024x1024"` - The content of the file to be sent to the model. + - `"1024x1536"` - - `file_id: optional string` + - `"1536x1024"` - The ID of the file to be sent to the model. + - `"auto"` - - `file_url: optional string` + - `LocalShell object { type }` - The URL of the file to be sent to the model. + A tool that allows the model to execute shell commands in a local environment. - - `filename: optional string` + - `type: "local_shell"` - The name of the file to be sent to the model. + The type of the local shell tool. Always `local_shell`. - - `prompt_cache_breakpoint: optional object { mode }` + - `"local_shell"` - 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. + - `Shell object { type, allowed_callers, environment }` - - `mode: "explicit"` + A tool that allows the model to execute shell commands. - The breakpoint mode. Always `explicit`. + - `type: "shell"` - - `"explicit"` + The type of the shell tool. Always `shell`. - - `role: "user" or "assistant" or "system" or "developer"` + - `"shell"` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"user"` + The tool invocation context(s). - - `"assistant"` + - `"direct"` - - `"system"` + - `"programmatic"` - - `"developer"` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `phase: optional "commentary" or "final_answer"` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + - `type: "container_auto"` - - `"commentary"` + Automatically creates a container for this request - - `"final_answer"` + - `"container_auto"` - - `type: optional "message"` + - `file_ids: optional array of string` - The type of the message input. Always `message`. + An optional list of uploaded files to make available to your code. - - `"message"` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `Message object { content, role, agent, 2 more }` + The memory limit for the container. - 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. + - `"1g"` - - `content: BetaResponseInputMessageContentList` + - `"4g"` - A list of one or many input items to the model, containing different content - types. + - `"16g"` - - `role: "user" or "system" or "developer"` + - `"64g"` - The role of the message input. One of `user`, `system`, or `developer`. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `"user"` + Network access policy for the container. - - `"system"` + - `BetaContainerNetworkPolicyDisabled object { type }` - - `"developer"` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `agent: optional object { agent_name }` + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - The agent that produced this item. + An optional list of skills referenced by id or inline data. - - `agent_name: string` + - `BetaSkillReference object { skill_id, type, version }` - The canonical name of the agent that produced this item. + - `skill_id: string` - - `status: optional "in_progress" or "completed" or "incomplete"` + The ID of the referenced skill. - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `type: "skill_reference"` - - `"in_progress"` + References a skill created with the /v1/skills endpoint. - - `"completed"` + - `"skill_reference"` - - `"incomplete"` + - `version: optional string` - - `type: optional "message"` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - The type of the message input. Always set to `message`. + - `BetaInlineSkill object { description, name, source, type }` - - `"message"` + - `description: string` - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + The description of the skill. - An output message from the model. + - `name: string` - - `id: string` + The name of the skill. - The unique ID of the output message. + - `source: BetaInlineSkillSource` - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + Inline skill payload - The content of the output message. + - `data: string` - - `BetaResponseOutputText object { annotations, logprobs, text, type }` + Base64-encoded skill zip bundle. - A text output from the model. + - `media_type: "application/zip"` - - `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 media type of the inline skill payload. Must be `application/zip`. - The annotations of the text output. + - `"application/zip"` - - `FileCitation object { file_id, filename, index, type }` + - `type: "base64"` - A citation to a file. + The type of the inline skill source. Must be `base64`. - - `file_id: string` + - `"base64"` - The ID of the file. + - `type: "inline"` - - `filename: string` + Defines an inline skill for this request. - The filename of the file cited. + - `"inline"` - - `index: number` + - `BetaLocalEnvironment object { type, skills }` - The index of the file in the list of files. + - `type: "local"` - - `type: "file_citation"` + Use a local computer environment. - The type of the file citation. Always `file_citation`. + - `"local"` - - `"file_citation"` + - `skills: optional array of BetaLocalSkill` - - `URLCitation object { end_index, start_index, title, 2 more }` + An optional list of skills. - A citation for a web resource used to generate a model response. + - `description: string` - - `end_index: number` + The description of the skill. - The index of the last character of the URL citation in the message. + - `name: string` - - `start_index: number` + The name of the skill. - The index of the first character of the URL citation in the message. + - `path: string` - - `title: string` + The path to the directory containing the skill. - The title of the web resource. + - `BetaContainerReference object { container_id, type }` - - `type: "url_citation"` + - `container_id: string` - The type of the URL citation. Always `url_citation`. + The ID of the referenced container. - - `"url_citation"` + - `type: "container_reference"` - - `url: string` + References a container created with the /v1/containers endpoint - The URL of the web resource. + - `"container_reference"` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + - `Custom object { name, type, allowed_callers, 3 more }` - A citation for a container file used to generate a model response. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `container_id: string` + - `name: string` - The ID of the container file. + The name of the custom tool, used to identify it in tool calls. - - `end_index: number` + - `type: "custom"` - The index of the last character of the container file citation in the message. + The type of the custom tool. Always `custom`. - - `file_id: string` + - `"custom"` - The ID of the file. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `filename: string` + The tool invocation context(s). - The filename of the container file cited. + - `"direct"` - - `start_index: number` + - `"programmatic"` - The index of the first character of the container file citation in the message. + - `defer_loading: optional boolean` - - `type: "container_file_citation"` + Whether this tool should be deferred and discovered via tool search. - The type of the container file citation. Always `container_file_citation`. + - `description: optional string` - - `"container_file_citation"` + Optional description of the custom tool, used to provide more context. - - `FilePath object { file_id, index, type }` + - `format: optional object { type } or object { definition, syntax, type }` - A path to a file. + The input format for the custom tool. Default is unconstrained text. - - `file_id: string` + - `Text object { type }` - The ID of the file. + Unconstrained free-form text. - - `index: number` + - `type: "text"` - The index of the file in the list of files. + Unconstrained text format. Always `text`. - - `type: "file_path"` + - `"text"` - The type of the file path. Always `file_path`. + - `Grammar object { definition, syntax, type }` - - `"file_path"` + A grammar defined by the user. - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `definition: string` - - `token: string` + The grammar definition. - - `bytes: array of number` + - `syntax: "lark" or "regex"` - - `logprob: number` + The syntax of the grammar definition. One of `lark` or `regex`. - - `top_logprobs: array of object { token, bytes, logprob }` + - `"lark"` - - `token: string` + - `"regex"` - - `bytes: array of number` + - `type: "grammar"` - - `logprob: number` + Grammar format. Always `grammar`. - - `text: string` + - `"grammar"` - The text output from the model. + - `Namespace object { description, name, tools, type }` - - `type: "output_text"` + Groups function/custom tools under a shared namespace. - The type of the output text. Always `output_text`. + - `description: string` - - `"output_text"` + A description of the namespace shown to the model. - - `BetaResponseOutputRefusal object { refusal, type }` + - `name: string` - A refusal from the model. + The namespace name used in tool calls (for example, `crm`). - - `refusal: string` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - The refusal explanation from the model. + The function/custom tools available inside this namespace. - - `type: "refusal"` + - `Function object { name, type, allowed_callers, 5 more }` - The type of the refusal. Always `refusal`. + - `name: string` - - `"refusal"` + - `type: "function"` - - `role: "assistant"` + - `"function"` - The role of the output message. Always `assistant`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"assistant"` + The tool invocation context(s). - - `status: "in_progress" or "completed" or "incomplete"` + - `"direct"` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `"programmatic"` - - `"in_progress"` + - `defer_loading: optional boolean` - - `"completed"` + Whether this function should be deferred and discovered via tool search. - - `"incomplete"` + - `description: optional string` - - `type: "message"` + - `output_schema: optional map[unknown]` - The type of the output message. Always `message`. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `"message"` + - `parameters: optional unknown` - - `agent: optional object { agent_name }` + - `strict: optional boolean` - The agent that produced this 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. - - `agent_name: string` + - `Custom object { name, type, allowed_callers, 3 more }` - The canonical name of the agent that produced this item. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `phase: optional "commentary" or "final_answer"` + - `name: 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 name of the custom tool, used to identify it in tool calls. - - `"commentary"` + - `type: "custom"` - - `"final_answer"` + The type of the custom tool. Always `custom`. - - `FileSearchCall object { id, queries, status, 3 more }` + - `"custom"` - The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `id: string` + The tool invocation context(s). - The unique ID of the file search tool call. + - `"direct"` - - `queries: array of string` + - `"programmatic"` - The queries used to search for files. + - `defer_loading: optional boolean` - - `status: "in_progress" or "searching" or "completed" or 2 more` + Whether this tool should be deferred and discovered via tool search. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `description: optional string` - - `"in_progress"` + Optional description of the custom tool, used to provide more context. - - `"searching"` + - `format: optional object { type } or object { definition, syntax, type }` - - `"completed"` + The input format for the custom tool. Default is unconstrained text. - - `"incomplete"` + - `Text object { type }` - - `"failed"` + Unconstrained free-form text. - - `type: "file_search_call"` + - `type: "text"` - The type of the file search tool call. Always `file_search_call`. + Unconstrained text format. Always `text`. - - `"file_search_call"` + - `"text"` - - `agent: optional object { agent_name }` + - `Grammar object { definition, syntax, type }` - The agent that produced this item. + A grammar defined by the user. - - `agent_name: string` + - `definition: string` - The canonical name of the agent that produced this item. + The grammar definition. - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `syntax: "lark" or "regex"` - The results of the file search tool call. + The syntax of the grammar definition. One of `lark` or `regex`. - - `attributes: optional map[string or number or boolean]` + - `"lark"` - 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. + - `"regex"` - - `string` + - `type: "grammar"` - - `number` + Grammar format. Always `grammar`. - - `boolean` + - `"grammar"` - - `file_id: optional string` + - `type: "namespace"` - The unique ID of the file. + The type of the tool. Always `namespace`. - - `filename: optional string` + - `"namespace"` - The name of the file. + - `ToolSearch object { type, description, execution, parameters }` - - `score: optional number` + Hosted or BYOT tool search configuration for deferred tools. - The relevance score of the file - a value between 0 and 1. + - `type: "tool_search"` - - `text: optional string` + The type of the tool. Always `tool_search`. - The text that was retrieved from the file. + - `"tool_search"` - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + - `description: optional string` - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + Description shown to the model for a client-executed tool search tool. - - `id: string` + - `execution: optional "server" or "client"` - The unique ID of the computer call. + Whether tool search is executed by the server or by the client. - - `call_id: string` + - `"server"` - An identifier used when responding to the tool call with output. + - `"client"` - - `pending_safety_checks: array of object { id, code, message }` + - `parameters: optional unknown` - The pending safety checks for the computer call. + Parameter schema for a client-executed tool search tool. - - `id: string` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - The ID of the pending safety check. + 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). - - `code: optional string` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - The type of the pending safety check. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `message: optional string` + - `"web_search_preview"` - Details about the pending safety check. + - `"web_search_preview_2025_03_11"` - - `status: "in_progress" or "completed" or "incomplete"` + - `search_content_types: optional array of "text" or "image"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"text"` - - `"in_progress"` + - `"image"` - - `"completed"` + - `search_context_size: optional "low" or "medium" or "high"` - - `"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. - - `type: "computer_call"` + - `"low"` - The type of the computer call. Always `computer_call`. + - `"medium"` - - `"computer_call"` + - `"high"` - - `action: optional BetaComputerAction` + - `user_location: optional object { type, city, country, 2 more }` - A click action. + The user's location. - - `Click object { button, type, x, 2 more }` + - `type: "approximate"` - A click action. + The type of location approximation. Always `approximate`. - - `button: "left" or "right" or "wheel" or 2 more` + - `"approximate"` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `city: optional string` - - `"left"` + Free text input for the city of the user, e.g. `San Francisco`. - - `"right"` + - `country: optional string` - - `"wheel"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"back"` + - `region: optional string` - - `"forward"` + Free text input for the region of the user, e.g. `California`. - - `type: "click"` + - `timezone: optional string` - Specifies the event type. For a click action, this property is always `click`. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"click"` + - `ApplyPatch object { type, allowed_callers }` - - `x: number` + Allows the assistant to create, delete, or update files using unified diffs. - The x-coordinate where the click occurred. + - `type: "apply_patch"` - - `y: number` + The type of the tool. Always `apply_patch`. - The y-coordinate where the click occurred. + - `"apply_patch"` - - `keys: optional array of string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The keys being held while clicking. + The tool invocation context(s). - - `DoubleClick object { keys, type, x, y }` + - `"direct"` - A double click action. + - `"programmatic"` - - `keys: array of string` + - `type: "tool_search_output"` - The keys being held while double-clicking. + The item type. Always `tool_search_output`. - - `type: "double_click"` + - `"tool_search_output"` - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `id: optional string` - - `"double_click"` + The unique ID of this tool search output. - - `x: number` + - `agent: optional object { agent_name }` - The x-coordinate where the double click occurred. + The agent that produced this item. - - `y: number` + - `agent_name: string` - The y-coordinate where the double click occurred. + The canonical name of the agent that produced this item. - - `Drag object { path, type, keys }` + - `call_id: optional string` - A drag action. + The unique ID of the tool search call generated by the model. - - `path: array of object { x, y }` + - `execution: optional "server" or "client"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + Whether tool search was executed by the server or by the client. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `"server"` - - `x: number` + - `"client"` - The x-coordinate. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `y: number` + The status of the tool search output. - The y-coordinate. + - `"in_progress"` - - `type: "drag"` + - `"completed"` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `"incomplete"` - - `"drag"` + - `AdditionalTools object { role, tools, type, 2 more }` - - `keys: optional array of string` + - `role: "developer"` - The keys being held while dragging the mouse. + The role that provided the additional tools. Only `developer` is supported. - - `Keypress object { keys, type }` + - `"developer"` - A collection of keypresses the model would like to perform. + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - - `keys: array of string` + A list of additional tools made available at this item. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `Function object { name, parameters, strict, 5 more }` - - `type: "keypress"` + 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). - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `name: string` - - `"keypress"` + The name of the function to call. - - `Move object { type, x, y, keys }` + - `parameters: map[unknown]` - A mouse move action. + A JSON schema object describing the parameters of the function. - - `type: "move"` + - `strict: boolean` - Specifies the event type. For a move action, this property is always set to `move`. + Whether strict parameter validation is enforced for this function tool. - - `"move"` + - `type: "function"` - - `x: number` + The type of the function tool. Always `function`. - The x-coordinate to move to. + - `"function"` - - `y: number` + - `allowed_callers: optional array of "direct" or "programmatic"` - The y-coordinate to move to. + The tool invocation context(s). - - `keys: optional array of string` + - `"direct"` - The keys being held while moving the mouse. + - `"programmatic"` - - `Screenshot object { type }` + - `defer_loading: optional boolean` - A screenshot action. + Whether this function is deferred and loaded via tool search. - - `type: "screenshot"` + - `description: optional string` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + A description of the function. Used by the model to determine whether or not to call the function. - - `"screenshot"` + - `output_schema: optional map[unknown]` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + A JSON schema object describing the JSON value encoded in string outputs for this function. - A scroll action. + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `scroll_x: number` + 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 horizontal scroll distance. + - `type: "file_search"` - - `scroll_y: number` + The type of the file search tool. Always `file_search`. - The vertical scroll distance. + - `"file_search"` - - `type: "scroll"` + - `vector_store_ids: array of string` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + The IDs of the vector stores to search. - - `"scroll"` + - `filters: optional object { key, type, value } or object { filters, type }` - - `x: number` + A filter to apply. - The x-coordinate where the scroll occurred. + - `ComparisonFilter object { key, type, value }` - - `y: number` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The y-coordinate where the scroll occurred. + - `key: string` - - `keys: optional array of string` + The key to compare against the value. - The keys being held while scrolling. + - `type: "eq" or "ne" or "gt" or 5 more` - - `Type object { text, type }` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - An action to type in text. + - `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 - - `text: string` + - `"eq"` - The text to type. + - `"ne"` - - `type: "type"` + - `"gt"` - Specifies the event type. For a type action, this property is always set to `type`. + - `"gte"` - - `"type"` + - `"lt"` - - `Wait object { type }` + - `"lte"` - A wait action. + - `"in"` - - `type: "wait"` + - `"nin"` - Specifies the event type. For a wait action, this property is always set to `wait`. + - `value: string or number or boolean or array of string or number` - - `"wait"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `actions: optional BetaComputerActionList` + - `string` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `number` - - `Click object { button, type, x, 2 more }` + - `boolean` - A click action. + - `array of string or number` - - `DoubleClick object { keys, type, x, y }` + - `string` - A double click action. + - `number` - - `Drag object { path, type, keys }` + - `CompoundFilter object { filters, type }` - A drag action. + Combine multiple filters using `and` or `or`. - - `Keypress object { keys, type }` + - `filters: array of object { key, type, value } or unknown` - A collection of keypresses the model would like to perform. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `Move object { type, x, y, keys }` + - `ComparisonFilter object { key, type, value }` - A mouse move action. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `Screenshot object { type }` + - `key: string` - A screenshot action. + The key to compare against the value. - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `type: "eq" or "ne" or "gt" or 5 more` - A scroll action. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `Type object { text, type }` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - An action to type in text. + - `"eq"` - - `Wait object { type }` + - `"ne"` - A wait action. + - `"gt"` - - `agent: optional object { agent_name }` + - `"gte"` - The agent that produced this item. + - `"lt"` - - `agent_name: string` + - `"lte"` - The canonical name of the agent that produced this item. + - `"in"` - - `ComputerCallOutput object { call_id, output, type, 4 more }` + - `"nin"` - The output of a computer tool call. + - `value: string or number or boolean or array of string or number` - - `call_id: string` + The value to compare against the attribute key; supports string, number, or boolean types. - The ID of the computer tool call that produced the output. + - `string` - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `number` - A computer screenshot image used with the computer use tool. + - `boolean` - - `type: "computer_screenshot"` + - `array of string or number` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `string` - - `"computer_screenshot"` + - `number` - - `file_id: optional string` + - `unknown` - The identifier of an uploaded file that contains the screenshot. + - `type: "and" or "or"` - - `image_url: optional string` + Type of operation: `and` or `or`. - The URL of the screenshot image. + - `"and"` - - `type: "computer_call_output"` + - `"or"` - The type of the computer tool call output. Always `computer_call_output`. + - `max_num_results: optional number` - - `"computer_call_output"` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `id: optional string` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - The ID of the computer tool call output. + Ranking options for search. - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `hybrid_search: optional object { embedding_weight, text_weight }` - The safety checks reported by the API that have been acknowledged by the developer. + 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 ID of the pending safety check. + The weight of the embedding in the reciprocal ranking fusion. - - `code: optional string` + - `text_weight: number` - The type of the pending safety check. + The weight of the text in the reciprocal ranking fusion. - - `message: optional string` + - `ranker: optional "auto" or "default-2024-11-15"` - Details about the pending safety check. + The ranker to use for the file search. - - `agent: optional object { agent_name }` + - `"auto"` - The agent that produced this item. + - `"default-2024-11-15"` - - `agent_name: string` + - `score_threshold: optional number` - The canonical name of the agent that produced this item. + 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. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `Computer object { type }` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"in_progress"` + - `type: "computer"` - - `"completed"` + The type of the computer tool. Always `computer`. - - `"incomplete"` + - `"computer"` - - `WebSearchCall object { id, action, status, 2 more }` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `id: string` + - `display_height: number` - The unique ID of the web search tool call. + The height of the computer display. - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `display_width: number` - An object describing the specific action taken in this web search call. - Includes details on how the model used the web (search, open_page, find_in_page). + The width of the computer display. - - `Search object { type, queries, query, sources }` + - `environment: "windows" or "mac" or "linux" or 2 more` - Action type "search" - Performs a web search query. + The type of computer environment to control. - - `type: "search"` + - `"windows"` - The action type. + - `"mac"` - - `"search"` + - `"linux"` - - `queries: optional array of string` + - `"ubuntu"` - The search queries. + - `"browser"` - - `query: optional string` + - `type: "computer_use_preview"` - The search query. + The type of the computer use tool. Always `computer_use_preview`. - - `sources: optional array of object { type, url }` + - `"computer_use_preview"` - The sources used in the search. + - `WebSearch object { type, filters, search_context_size, user_location }` - - `type: "url"` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - The type of source. Always `url`. + - `type: "web_search" or "web_search_2025_08_26"` - - `"url"` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `url: string` + - `"web_search"` - The URL of the source. + - `"web_search_2025_08_26"` - - `OpenPage object { type, url }` + - `filters: optional object { allowed_domains }` - Action type "open_page" - Opens a specific URL from search results. + Filters for the search. - - `type: "open_page"` + - `allowed_domains: optional array of string` - The action type. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `"open_page"` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `url: optional string` + - `search_context_size: optional "low" or "medium" or "high"` - The URL opened by 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. - - `FindInPage object { pattern, type, url }` + - `"low"` - Action type "find_in_page": Searches for a pattern within a loaded page. + - `"medium"` - - `pattern: string` + - `"high"` - The pattern or text to search for within the page. + - `user_location: optional object { city, country, region, 2 more }` - - `type: "find_in_page"` + The approximate location of the user. - The action type. + - `city: optional string` - - `"find_in_page"` + Free text input for the city of the user, e.g. `San Francisco`. - - `url: string` + - `country: optional string` - The URL of the page searched for the pattern. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `region: optional string` - The status of the web search tool call. + Free text input for the region of the user, e.g. `California`. - - `"in_progress"` + - `timezone: optional string` - - `"searching"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"completed"` + - `type: optional "approximate"` - - `"failed"` + The type of location approximation. Always `approximate`. - - `type: "web_search_call"` + - `"approximate"` - The type of the web search tool call. Always `web_search_call`. + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `"web_search_call"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `agent: optional object { agent_name }` + - `server_label: string` - The agent that produced this item. + A label for this MCP server, used to identify it in tool calls. - - `agent_name: string` + - `type: "mcp"` - The canonical name of the agent that produced this item. + The type of the MCP tool. Always `mcp`. - - `FunctionCall object { arguments, call_id, name, 6 more }` + - `"mcp"` - 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. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `name: string` + List of allowed tool names or a filter object. - The name of the function to run. + - `McpAllowedTools = array of string` - - `type: "function_call"` + A string array of allowed tool names - The type of the function tool call. Always `function_call`. + - `McpToolFilter object { read_only, tool_names }` - - `"function_call"` + A filter object to specify which tools are allowed. - - `id: optional string` + - `read_only: optional boolean` - The unique ID of the function 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. - - `agent: optional object { agent_name }` + - `tool_names: optional array of string` - The agent that produced this item. + List of allowed tool names. - - `agent_name: string` + - `authorization: optional string` - The canonical name of the agent that produced this item. + 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` - - `"direct"` + - `"connector_dropbox"` - - `Program object { caller_id, type }` + - `"connector_gmail"` - - `caller_id: string` + - `"connector_googlecalendar"` - The call ID of the program item that produced this tool call. + - `"connector_googledrive"` - - `type: "program"` + - `"connector_microsoftteams"` - - `"program"` + - `"connector_outlookcalendar"` - - `namespace: optional string` + - `"connector_outlookemail"` - The namespace of the function to run. + - `"connector_sharepoint"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `defer_loading: optional boolean` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Whether this MCP tool is deferred and discovered via tool search. - - `"in_progress"` + - `headers: optional map[string]` - - `"completed"` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `"incomplete"` + - `require_approval: optional object { always, never } or "always" or "never"` - - `FunctionCallOutput object { call_id, output, type, 4 more }` + Specify which of the MCP server's tools require approval. - The output of a function tool call. + - `McpToolApprovalFilter object { always, never }` - - `call_id: string` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - The unique ID of the function tool call generated by the model. + - `always: optional object { read_only, tool_names }` - - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` + A filter object to specify which tools are allowed. - Text, image, or file output of the function tool call. + - `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. - A JSON string of the output of the function tool call. + - `tool_names: optional array of string` - - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` + List of allowed tool names. - An array of content outputs (text, image, file) for the function tool call. + - `never: optional object { read_only, tool_names }` - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + A filter object to specify which tools are allowed. - A text input to the model. + - `read_only: optional boolean` - - `text: 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 text input to the model. + - `tool_names: optional array of string` - - `type: "input_text"` + List of allowed tool names. - The type of the input item. Always `input_text`. + - `McpToolApprovalSetting = "always" or "never"` - - `"input_text"` + 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_breakpoint: optional object { mode }` + - `"always"` - 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. + - `"never"` - - `mode: "explicit"` + - `server_description: optional string` - The breakpoint mode. Always `explicit`. + Optional description of the MCP server, used to provide more context. - - `"explicit"` + - `server_url: optional string` - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - An image input to the model. Learn about [image inputs](/docs/guides/vision) + - `tunnel_id: optional string` - - `type: "input_image"` + 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 type of the input item. Always `input_image`. + - `CodeInterpreter object { container, type, allowed_callers }` - - `"input_image"` + A tool that runs Python code to help generate a response to a prompt. - - `detail: optional "low" or "high" or "auto" or "original"` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + 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. - - `"low"` + - `string` - - `"high"` + The container ID. - - `"auto"` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `"original"` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `file_id: optional string` + - `type: "auto"` - The ID of the file to be sent to the model. + Always `auto`. - - `image_url: optional string` + - `"auto"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `file_ids: optional array of string` - - `prompt_cache_breakpoint: optional object { mode }` + An optional list of uploaded files to make available to your code. - 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. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `mode: "explicit"` + The memory limit for the code interpreter container. - The breakpoint mode. Always `explicit`. + - `"1g"` - - `"explicit"` + - `"4g"` - - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` + - `"16g"` - A file input to the model. + - `"64g"` - - `type: "input_file"` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - The type of the input item. Always `input_file`. + Network access policy for the container. - - `"input_file"` + - `BetaContainerNetworkPolicyDisabled object { type }` - - `detail: optional "auto" or "low" or "high"` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - 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: "code_interpreter"` - - `"auto"` + The type of the code interpreter tool. Always `code_interpreter`. - - `"low"` + - `"code_interpreter"` - - `"high"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `file_data: optional string` + The tool invocation context(s). - The base64-encoded data of the file to be sent to the model. + - `"direct"` - - `file_id: optional string` + - `"programmatic"` - The ID of the file to be sent to the model. + - `ProgrammaticToolCalling object { type }` - - `file_url: optional string` + - `type: "programmatic_tool_calling"` - The URL of the file to be sent to the model. + The type of the tool. Always `programmatic_tool_calling`. - - `filename: optional string` + - `"programmatic_tool_calling"` - The name of the file to be sent to the model. + - `ImageGeneration object { type, action, background, 9 more }` - - `prompt_cache_breakpoint: optional object { mode }` + A tool that generates images using the GPT image models. - 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: "image_generation"` - - `mode: "explicit"` + The type of the image generation tool. Always `image_generation`. - The breakpoint mode. Always `explicit`. + - `"image_generation"` - - `"explicit"` + - `action: optional "generate" or "edit" or "auto"` - - `type: "function_call_output"` + Whether to generate a new image or edit an existing image. Default: `auto`. - The type of the function tool call output. Always `function_call_output`. + - `"generate"` - - `"function_call_output"` + - `"edit"` - - `id: optional string` + - `"auto"` - The unique ID of the function tool call output. Populated when this item is returned via API. + - `background: optional "transparent" or "opaque" or "auto"` - - `agent: optional object { agent_name }` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - The agent that produced this item. + - `"transparent"` - - `agent_name: string` + - `"opaque"` - The canonical name of the agent that produced this item. + - `"auto"` - - `caller: optional object { type } or object { caller_id, type }` + - `input_fidelity: optional "high" or "low"` - The execution context that produced this tool call. + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `Direct object { type }` + - `"high"` - - `type: "direct"` + - `"low"` - The caller type. Always `direct`. + - `input_image_mask: optional object { file_id, image_url }` - - `"direct"` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `Program object { caller_id, type }` + - `file_id: optional string` - - `caller_id: string` + File ID for the mask image. - The call ID of the program item that produced this tool call. + - `image_url: optional string` - - `type: "program"` + Base64-encoded mask image. - The caller type. Always `program`. + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `"program"` + The image generation model to use. Default: `gpt-image-1`. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `string` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `"in_progress"` + The image generation model to use. Default: `gpt-image-1`. - - `"completed"` + - `"gpt-image-1"` - - `"incomplete"` + - `"gpt-image-1-mini"` - - `AgentMessage object { author, content, recipient, 3 more }` + - `"gpt-image-1.5"` - A message routed between agents. + - `moderation: optional "auto" or "low"` - - `author: string` + Moderation level for the generated image. Default: `auto`. - The sending agent identity. + - `"auto"` - - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` + - `"low"` - Plaintext, image, or encrypted content sent between agents. + - `output_compression: optional number` - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + Compression level for the output image. Default: 100. - A text input to the model. + - `output_format: optional "png" or "webp" or "jpeg"` - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - An image input to the model. Learn about [image inputs](/docs/guides/vision) + - `"png"` - - `EncryptedContent object { encrypted_content, type }` + - `"webp"` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `"jpeg"` - - `encrypted_content: string` + - `partial_images: optional number` - Opaque encrypted content. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `type: "encrypted_content"` + - `quality: optional "low" or "medium" or "high" or "auto"` - The type of the input item. Always `encrypted_content`. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `"encrypted_content"` + - `"low"` - - `recipient: string` + - `"medium"` - The destination agent identity. + - `"high"` - - `type: "agent_message"` + - `"auto"` - The item type. Always `agent_message`. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `"agent_message"` + 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: optional string` + - `string` - The unique ID of this agent message item. + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `agent: optional object { agent_name }` + 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 agent that produced this item. + - `"1024x1024"` - - `agent_name: string` + - `"1024x1536"` - The canonical name of the agent that produced this item. + - `"1536x1024"` - - `MultiAgentCall object { action, arguments, call_id, 3 more }` + - `"auto"` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `LocalShell object { type }` - The multi-agent action that was executed. + A tool that allows the model to execute shell commands in a local environment. - - `"spawn_agent"` + - `type: "local_shell"` - - `"interrupt_agent"` + The type of the local shell tool. Always `local_shell`. - - `"list_agents"` + - `"local_shell"` - - `"send_message"` + - `Shell object { type, allowed_callers, environment }` - - `"followup_task"` + A tool that allows the model to execute shell commands. - - `"wait_agent"` + - `type: "shell"` - - `arguments: string` + The type of the shell tool. Always `shell`. - The action arguments as a JSON string. + - `"shell"` - - `call_id: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The unique ID linking this call to its output. + The tool invocation context(s). - - `type: "multi_agent_call"` + - `"direct"` - The item type. Always `multi_agent_call`. + - `"programmatic"` - - `"multi_agent_call"` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `id: optional string` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - The unique ID of this multi-agent call. + - `BetaLocalEnvironment object { type, skills }` - - `agent: optional object { agent_name }` + - `BetaContainerReference object { container_id, type }` - The agent that produced this item. + - `Custom object { name, type, allowed_callers, 3 more }` - - `agent_name: string` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - The canonical name of the agent that produced this item. + - `name: string` - - `MultiAgentCallOutput object { action, call_id, output, 3 more }` + The name of the custom tool, used to identify it in tool calls. - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `type: "custom"` - The multi-agent action that produced this result. + The type of the custom tool. Always `custom`. - - `"spawn_agent"` + - `"custom"` - - `"interrupt_agent"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"list_agents"` + The tool invocation context(s). - - `"send_message"` + - `"direct"` - - `"followup_task"` + - `"programmatic"` - - `"wait_agent"` + - `defer_loading: optional boolean` - - `call_id: string` + Whether this tool should be deferred and discovered via tool search. - The unique ID of the multi-agent call. + - `description: optional string` - - `output: array of object { text, type, annotations }` + Optional description of the custom tool, used to provide more context. - Text output returned by the multi-agent action. + - `format: optional object { type } or object { definition, syntax, type }` - - `text: string` + The input format for the custom tool. Default is unconstrained text. - The text content. + - `Text object { type }` - - `type: "output_text"` + Unconstrained free-form text. - The content type. Always `output_text`. + - `type: "text"` - - `"output_text"` + Unconstrained text format. Always `text`. - - `annotations: optional 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 }` + - `"text"` - Citations associated with the text content. + - `Grammar object { definition, syntax, type }` - - `FileCitation object { file_id, filename, index, type }` + A grammar defined by the user. - - `file_id: string` + - `definition: string` - The ID of the file. + The grammar definition. - - `filename: string` + - `syntax: "lark" or "regex"` - The filename of the file cited. + The syntax of the grammar definition. One of `lark` or `regex`. - - `index: number` + - `"lark"` - The index of the file in the list of files. + - `"regex"` - - `type: "file_citation"` + - `type: "grammar"` - The citation type. Always `file_citation`. + Grammar format. Always `grammar`. - - `"file_citation"` + - `"grammar"` - - `URLCitation object { end_index, start_index, title, 2 more }` + - `Namespace object { description, name, tools, type }` - - `end_index: number` + Groups function/custom tools under a shared namespace. - The index of the last character of the citation in the message. + - `description: string` - - `start_index: number` + A description of the namespace shown to the model. - The index of the first character of the citation in the message. + - `name: string` - - `title: string` + The namespace name used in tool calls (for example, `crm`). - The title of the cited resource. + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `type: "url_citation"` + The function/custom tools available inside this namespace. - The citation type. Always `url_citation`. + - `Function object { name, type, allowed_callers, 5 more }` - - `"url_citation"` + - `name: string` - - `url: string` + - `type: "function"` - The URL of the cited resource. + - `"function"` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `container_id: string` + The tool invocation context(s). - The ID of the container. + - `"direct"` - - `end_index: number` + - `"programmatic"` - The index of the last character of the citation in the message. + - `defer_loading: optional boolean` - - `file_id: string` + Whether this function should be deferred and discovered via tool search. - The ID of the container file. + - `description: optional string` - - `filename: string` + - `output_schema: optional map[unknown]` - The filename of the container file cited. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `start_index: number` + - `parameters: optional unknown` - The index of the first character of the citation in the message. + - `strict: optional boolean` - - `type: "container_file_citation"` + 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 citation type. Always `container_file_citation`. + - `Custom object { name, type, allowed_callers, 3 more }` - - `"container_file_citation"` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `type: "multi_agent_call_output"` + - `name: string` - The item type. Always `multi_agent_call_output`. + The name of the custom tool, used to identify it in tool calls. - - `"multi_agent_call_output"` + - `type: "custom"` - - `id: optional string` + The type of the custom tool. Always `custom`. - The unique ID of this multi-agent call output. + - `"custom"` - - `agent: optional object { agent_name }` + - `allowed_callers: optional array of "direct" or "programmatic"` - The agent that produced this item. + The tool invocation context(s). - - `agent_name: string` + - `"direct"` - The canonical name of the agent that produced this item. + - `"programmatic"` - - `ToolSearchCall object { arguments, type, id, 4 more }` + - `defer_loading: optional boolean` - - `arguments: unknown` + Whether this tool should be deferred and discovered via tool search. - The arguments supplied to the tool search call. + - `description: optional string` - - `type: "tool_search_call"` + Optional description of the custom tool, used to provide more context. - The item type. Always `tool_search_call`. + - `format: optional object { type } or object { definition, syntax, type }` - - `"tool_search_call"` + The input format for the custom tool. Default is unconstrained text. - - `id: optional string` + - `Text object { type }` - The unique ID of this tool search call. + Unconstrained free-form text. - - `agent: optional object { agent_name }` + - `type: "text"` - The agent that produced this item. + Unconstrained text format. Always `text`. - - `agent_name: string` + - `"text"` - The canonical name of the agent that produced this item. + - `Grammar object { definition, syntax, type }` - - `call_id: optional string` + A grammar defined by the user. - The unique ID of the tool search call generated by the model. + - `definition: string` - - `execution: optional "server" or "client"` + The grammar definition. - Whether tool search was executed by the server or by the client. + - `syntax: "lark" or "regex"` - - `"server"` + The syntax of the grammar definition. One of `lark` or `regex`. - - `"client"` + - `"lark"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"regex"` - The status of the tool search call. + - `type: "grammar"` - - `"in_progress"` + Grammar format. Always `grammar`. - - `"completed"` + - `"grammar"` - - `"incomplete"` + - `type: "namespace"` - - `ToolSearchOutput object { tools, type, id, 4 more }` + The type of the tool. Always `namespace`. - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + - `"namespace"` - The loaded tool definitions returned by the tool search output. + - `ToolSearch object { type, description, execution, parameters }` - - `Function object { name, parameters, strict, 5 more }` + Hosted or BYOT tool search configuration for deferred tools. - 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: "tool_search"` - - `name: string` + The type of the tool. Always `tool_search`. - The name of the function to call. + - `"tool_search"` - - `parameters: map[unknown]` + - `description: optional string` - A JSON schema object describing the parameters of the function. + Description shown to the model for a client-executed tool search tool. - - `strict: boolean` + - `execution: optional "server" or "client"` - Whether strict parameter validation is enforced for this function tool. + Whether tool search is executed by the server or by the client. - - `type: "function"` + - `"server"` - The type of the function tool. Always `function`. + - `"client"` - - `"function"` + - `parameters: optional unknown` - - `allowed_callers: optional array of "direct" or "programmatic"` + Parameter schema for a client-executed tool search tool. - The tool invocation context(s). + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `"direct"` + 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). - - `"programmatic"` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `defer_loading: optional boolean` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - Whether this function is deferred and loaded via tool search. + - `"web_search_preview"` - - `description: optional string` + - `"web_search_preview_2025_03_11"` - A description of the function. Used by the model to determine whether or not to call the function. + - `search_content_types: optional array of "text" or "image"` - - `output_schema: optional map[unknown]` + - `"text"` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `"image"` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `search_context_size: optional "low" or "medium" or "high"` - 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). + 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: "file_search"` + - `"low"` - The type of the file search tool. Always `file_search`. + - `"medium"` - - `"file_search"` + - `"high"` - - `vector_store_ids: array of string` + - `user_location: optional object { type, city, country, 2 more }` - The IDs of the vector stores to search. + The user's location. - - `filters: optional object { key, type, value } or object { filters, type }` + - `type: "approximate"` - A filter to apply. + The type of location approximation. Always `approximate`. - - `ComparisonFilter object { key, type, value }` + - `"approximate"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `city: optional string` - - `key: string` + Free text input for the city of the user, e.g. `San Francisco`. - The key to compare against the value. + - `country: optional string` - - `type: "eq" or "ne" or "gt" or 5 more` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `region: optional string` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + Free text input for the region of the user, e.g. `California`. - - `"eq"` + - `timezone: optional string` - - `"ne"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"gt"` + - `ApplyPatch object { type, allowed_callers }` - - `"gte"` + Allows the assistant to create, delete, or update files using unified diffs. - - `"lt"` + - `type: "apply_patch"` - - `"lte"` + The type of the tool. Always `apply_patch`. - - `"in"` + - `"apply_patch"` - - `"nin"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `value: string or number or boolean or array of string or number` + The tool invocation context(s). - The value to compare against the attribute key; supports string, number, or boolean types. + - `"direct"` - - `string` + - `"programmatic"` - - `number` + - `type: "additional_tools"` - - `boolean` + The item type. Always `additional_tools`. - - `array of string or number` + - `"additional_tools"` - - `string` + - `id: optional string` - - `number` + The unique ID of this additional tools item. - - `CompoundFilter object { filters, type }` + - `agent: optional object { agent_name }` - Combine multiple filters using `and` or `or`. + The agent that produced this item. - - `filters: array of object { key, type, value } or unknown` + - `agent_name: string` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + The canonical name of the agent that produced this item. - - `ComparisonFilter object { key, type, value }` + - `Reasoning object { id, summary, type, 4 more }` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + 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). - - `key: string` + - `id: string` - The key to compare against the value. + The unique identifier of the reasoning content. - - `type: "eq" or "ne" or "gt" or 5 more` + - `summary: array of object { text, type }` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + Reasoning summary content. - - `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 + - `text: string` - - `"eq"` + A summary of the reasoning output from the model so far. - - `"ne"` + - `type: "summary_text"` - - `"gt"` + The type of the object. Always `summary_text`. - - `"gte"` + - `"summary_text"` - - `"lt"` + - `type: "reasoning"` - - `"lte"` + The type of the object. Always `reasoning`. - - `"in"` + - `"reasoning"` - - `"nin"` + - `agent: optional object { agent_name }` - - `value: string or number or boolean or array of string or number` + The agent that produced this item. - The value to compare against the attribute key; supports string, number, or boolean types. + - `agent_name: string` - - `string` + The canonical name of the agent that produced this item. - - `number` + - `content: optional array of object { text, type }` - - `boolean` + Reasoning text content. - - `array of string or number` + - `text: string` - - `string` + The reasoning text from the model. - - `number` + - `type: "reasoning_text"` - - `unknown` + The type of the reasoning text. Always `reasoning_text`. - - `type: "and" or "or"` + - `"reasoning_text"` - Type of operation: `and` or `or`. + - `encrypted_content: optional string` - - `"and"` + 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. - - `"or"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `max_num_results: optional number` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `"in_progress"` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `"completed"` - Ranking options for search. + - `"incomplete"` - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `Compaction object { encrypted_content, type, id, agent }` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - - `embedding_weight: number` + - `encrypted_content: string` - The weight of the embedding in the reciprocal ranking fusion. + The encrypted content of the compaction summary. - - `text_weight: number` + - `type: "compaction"` - The weight of the text in the reciprocal ranking fusion. + The type of the item. Always `compaction`. - - `ranker: optional "auto" or "default-2024-11-15"` + - `"compaction"` - The ranker to use for the file search. + - `id: optional string` - - `"auto"` + The ID of the compaction item. - - `"default-2024-11-15"` + - `agent: optional object { agent_name }` - - `score_threshold: optional number` + The agent that produced this item. - 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. + - `agent_name: string` - - `Computer object { type }` + The canonical name of the agent that produced this item. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `ImageGenerationCall object { id, result, status, 2 more }` - - `type: "computer"` + An image generation request made by the model. - The type of the computer tool. Always `computer`. + - `id: string` - - `"computer"` + The unique ID of the image generation call. - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `result: string` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The generated image encoded in base64. - - `display_height: number` + - `status: "in_progress" or "completed" or "generating" or "failed"` - The height of the computer display. + The status of the image generation call. - - `display_width: number` + - `"in_progress"` - The width of the computer display. + - `"completed"` - - `environment: "windows" or "mac" or "linux" or 2 more` + - `"generating"` - The type of computer environment to control. + - `"failed"` - - `"windows"` + - `type: "image_generation_call"` - - `"mac"` + The type of the image generation call. Always `image_generation_call`. - - `"linux"` + - `"image_generation_call"` - - `"ubuntu"` + - `agent: optional object { agent_name }` - - `"browser"` + The agent that produced this item. - - `type: "computer_use_preview"` + - `agent_name: string` - The type of the computer use tool. Always `computer_use_preview`. + The canonical name of the agent that produced this item. - - `"computer_use_preview"` + - `CodeInterpreterCall object { id, code, container_id, 4 more }` - - `WebSearch object { type, filters, search_context_size, user_location }` + A tool call to run code. - 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 code interpreter tool call. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `code: string` - - `"web_search"` + The code to run, or null if not available. - - `"web_search_2025_08_26"` + - `container_id: string` - - `filters: optional object { allowed_domains }` + The ID of the container used to run the code. - Filters for the search. + - `outputs: array of object { logs, type } or object { type, url }` - - `allowed_domains: optional array of string` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `Logs object { logs, type }` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The logs output from the code interpreter. - - `search_context_size: optional "low" or "medium" or "high"` + - `logs: 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 logs output from the code interpreter. - - `"low"` + - `type: "logs"` - - `"medium"` + The type of the output. Always `logs`. - - `"high"` + - `"logs"` - - `user_location: optional object { city, country, region, 2 more }` + - `Image object { type, url }` - The approximate location of the user. + The image output from the code interpreter. - - `city: optional string` + - `type: "image"` - Free text input for the city of the user, e.g. `San Francisco`. + The type of the output. Always `image`. - - `country: optional string` + - `"image"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `url: string` - - `region: optional string` + The URL of the image output from the code interpreter. - Free text input for the region of the user, e.g. `California`. + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - `timezone: optional string` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"in_progress"` - - `type: optional "approximate"` + - `"completed"` - The type of location approximation. Always `approximate`. + - `"incomplete"` - - `"approximate"` + - `"interpreting"` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `"failed"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + - `type: "code_interpreter_call"` - - `server_label: string` + The type of the code interpreter tool call. Always `code_interpreter_call`. - A label for this MCP server, used to identify it in tool calls. + - `"code_interpreter_call"` - - `type: "mcp"` + - `agent: optional object { agent_name }` - The type of the MCP tool. Always `mcp`. + The agent that produced this item. - - `"mcp"` + - `agent_name: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The canonical name of the agent that produced this item. - The tool invocation context(s). + - `LocalShellCall object { id, action, call_id, 3 more }` - - `"direct"` + A tool call to run a command on the local shell. - - `"programmatic"` + - `id: string` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + The unique ID of the local shell call. - List of allowed tool names or a filter object. + - `action: object { command, env, type, 3 more }` - - `McpAllowedTools = array of string` + Execute a shell command on the server. - A string array of allowed tool names + - `command: array of string` - - `McpToolFilter object { read_only, tool_names }` + The command to run. - A filter object to specify which tools are allowed. + - `env: map[string]` - - `read_only: optional boolean` + Environment variables to set for the command. - 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: "exec"` - - `tool_names: optional array of string` + The type of the local shell action. Always `exec`. - List of allowed tool names. + - `"exec"` - - `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. + Optional timeout in milliseconds for the command. - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `user: optional 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). + Optional user to run the command as. - Currently supported `connector_id` values are: + - `working_directory: optional string` - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + Optional working directory to run the command in. - - `"connector_dropbox"` + - `call_id: string` - - `"connector_gmail"` + The unique ID of the local shell tool call generated by the model. - - `"connector_googlecalendar"` + - `status: "in_progress" or "completed" or "incomplete"` - - `"connector_googledrive"` + The status of the local shell call. - - `"connector_microsoftteams"` + - `"in_progress"` - - `"connector_outlookcalendar"` + - `"completed"` - - `"connector_outlookemail"` + - `"incomplete"` - - `"connector_sharepoint"` + - `type: "local_shell_call"` - - `defer_loading: optional boolean` + The type of the local shell call. Always `local_shell_call`. - Whether this MCP tool is deferred and discovered via tool search. + - `"local_shell_call"` - - `headers: optional map[string]` + - `agent: optional object { agent_name }` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The agent that produced this item. - - `require_approval: optional object { always, never } or "always" or "never"` + - `agent_name: string` - Specify which of the MCP server's tools require approval. + The canonical name of the agent that produced this item. - - `McpToolApprovalFilter object { always, never }` + - `LocalShellCallOutput object { id, output, type, 2 more }` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + The output of a local shell tool call. - - `always: optional object { read_only, tool_names }` + - `id: string` - A filter object to specify which tools are allowed. + The unique ID of the local shell tool call generated by the model. - - `read_only: optional boolean` + - `output: 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. + A JSON string of the output of the local shell tool call. - - `tool_names: optional array of string` + - `type: "local_shell_call_output"` - List of allowed tool names. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `never: optional object { read_only, tool_names }` + - `"local_shell_call_output"` - A filter object to specify which tools are allowed. + - `agent: optional object { agent_name }` - - `read_only: optional boolean` + The agent that produced this item. - 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. + - `agent_name: string` - - `tool_names: optional array of string` + The canonical name of the agent that produced this item. - List of allowed tool names. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `McpToolApprovalSetting = "always" or "never"` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `"in_progress"` - - `"always"` + - `"completed"` - - `"never"` + - `"incomplete"` - - `server_description: optional string` + - `ShellCall object { action, call_id, type, 5 more }` - Optional description of the MCP server, used to provide more context. + A tool representing a request to execute one or more shell commands. - - `server_url: optional string` + - `action: object { commands, max_output_length, timeout_ms }` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + The shell commands and limits that describe how to run the tool call. - - `tunnel_id: optional string` + - `commands: array of string` - The Secure MCP Tunnel ID to use instead of a direct server URL. One of - `server_url`, `connector_id`, or `tunnel_id` must be provided. + Ordered shell commands for the execution environment to run. - - `CodeInterpreter object { container, type, allowed_callers }` + - `max_output_length: optional number` - A tool that runs Python code to help generate a response to a prompt. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `timeout_ms: optional 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. + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `string` + - `call_id: string` - The container ID. + The unique ID of the shell tool call generated by the model. - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `type: "shell_call"` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + The type of the item. Always `shell_call`. - - `type: "auto"` + - `"shell_call"` - Always `auto`. + - `id: optional string` - - `"auto"` + The unique ID of the shell tool call. Populated when this item is returned via API. - - `file_ids: optional array of string` + - `agent: optional object { agent_name }` - An optional list of uploaded files to make available to your code. + The agent that produced this item. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `agent_name: string` - The memory limit for the code interpreter container. + The canonical name of the agent that produced this item. - - `"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 BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + The caller type. Always `direct`. - Network access policy for the container. + - `"direct"` - - `BetaContainerNetworkPolicyDisabled object { type }` + - `Program object { caller_id, type }` - - `type: "disabled"` + - `caller_id: string` - Disable outbound network access. Always `disabled`. + The call ID of the program item that produced this tool call. - - `"disabled"` + - `type: "program"` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + The caller type. Always `program`. - - `allowed_domains: array of string` + - `"program"` - A list of allowed domains when type is `allowlist`. + - `environment: optional BetaLocalEnvironment or BetaContainerReference` - - `type: "allowlist"` + The environment to execute the shell commands in. - Allow outbound network access only to specified domains. Always `allowlist`. + - `BetaLocalEnvironment object { type, skills }` - - `"allowlist"` + - `BetaContainerReference object { container_id, type }` - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + - `status: optional "in_progress" or "completed" or "incomplete"` - Optional domain-scoped secrets for allowlisted domains. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `domain: string` + - `"in_progress"` - The domain associated with the secret. + - `"completed"` - - `name: string` + - `"incomplete"` - The name of the secret to inject for the domain. + - `ShellCallOutput object { call_id, output, type, 5 more }` - - `value: string` + The streamed output items emitted by a shell tool call. - The secret value to inject for the domain. + - `call_id: string` - - `type: "code_interpreter"` + The unique ID of the shell tool call generated by the model. - The type of the code interpreter tool. Always `code_interpreter`. + - `output: array of BetaResponseFunctionShellCallOutputContent` - - `"code_interpreter"` + Captured chunks of stdout and stderr output, along with their associated outcomes. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `outcome: object { type } or object { exit_code, type }` - The tool invocation context(s). + The exit or timeout outcome associated with this shell call. - - `"direct"` + - `Timeout object { type }` - - `"programmatic"` + Indicates that the shell call exceeded its configured time limit. - - `ProgrammaticToolCalling object { type }` + - `type: "timeout"` - - `type: "programmatic_tool_calling"` + The outcome type. Always `timeout`. - The type of the tool. Always `programmatic_tool_calling`. + - `"timeout"` - - `"programmatic_tool_calling"` + - `Exit object { exit_code, type }` - - `ImageGeneration object { type, action, background, 9 more }` + Indicates that the shell commands finished and returned an exit code. - A tool that generates images using the GPT image models. + - `exit_code: number` - - `type: "image_generation"` + The exit code returned by the shell process. - The type of the image generation tool. Always `image_generation`. + - `type: "exit"` - - `"image_generation"` + The outcome type. Always `exit`. - - `action: optional "generate" or "edit" or "auto"` + - `"exit"` - Whether to generate a new image or edit an existing image. Default: `auto`. + - `stderr: string` - - `"generate"` + Captured stderr output for the shell call. - - `"edit"` + - `stdout: string` - - `"auto"` + Captured stdout output for the shell call. - - `background: optional "transparent" or "opaque" or "auto"` + - `type: "shell_call_output"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + The type of the item. Always `shell_call_output`. - - `"transparent"` + - `"shell_call_output"` - - `"opaque"` + - `id: optional string` - - `"auto"` + The unique ID of the shell tool call output. Populated when this item is returned via API. - - `input_fidelity: optional "high" or "low"` + - `agent: optional object { agent_name }` - 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 agent that produced this item. - - `"high"` + - `agent_name: string` - - `"low"` + The canonical name of the agent that produced this item. - - `input_image_mask: optional object { file_id, image_url }` + - `caller: optional object { type } or object { caller_id, type }` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + The execution context that produced this tool call. - - `file_id: optional string` + - `Direct object { type }` - File ID for the mask image. + - `type: "direct"` - - `image_url: optional string` + The caller type. Always `direct`. - Base64-encoded mask image. + - `"direct"` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `Program object { caller_id, type }` - The image generation model to use. Default: `gpt-image-1`. + - `caller_id: string` - - `string` + The call ID of the program item that produced this tool call. - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `type: "program"` - The image generation model to use. Default: `gpt-image-1`. + The caller type. Always `program`. - - `"gpt-image-1"` + - `"program"` - - `"gpt-image-1-mini"` + - `max_output_length: optional number` - - `"gpt-image-1.5"` + The maximum number of UTF-8 characters captured for this shell call's combined output. - - `moderation: optional "auto" or "low"` + - `status: optional "in_progress" or "completed" or "incomplete"` - Moderation level for the generated image. Default: `auto`. + The status of the shell call output. - - `"auto"` + - `"in_progress"` - - `"low"` + - `"completed"` - - `output_compression: optional number` + - `"incomplete"` - Compression level for the output image. Default: 100. + - `ApplyPatchCall object { call_id, operation, status, 4 more }` - - `output_format: optional "png" or "webp" or "jpeg"` + A tool call representing a request to create, delete, or update files using diff patches. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `call_id: string` - - `"png"` + The unique ID of the apply patch tool call generated by the model. - - `"webp"` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - `"jpeg"` + The specific create, delete, or update instruction for the apply_patch tool call. - - `partial_images: optional number` + - `CreateFile object { diff, path, type }` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + Instruction for creating a new file via the apply_patch tool. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `diff: string` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + Unified diff content to apply when creating the file. - - `"low"` + - `path: string` - - `"medium"` + Path of the file to create relative to the workspace root. - - `"high"` + - `type: "create_file"` - - `"auto"` + The operation type. Always `create_file`. - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `"create_file"` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `DeleteFile object { path, type }` - - `string` + Instruction for deleting an existing file via the apply_patch tool. - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `path: 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`. + Path of the file to delete relative to the workspace root. - - `"1024x1024"` + - `type: "delete_file"` - - `"1024x1536"` + The operation type. Always `delete_file`. - - `"1536x1024"` + - `"delete_file"` - - `"auto"` + - `UpdateFile object { diff, path, type }` - - `LocalShell object { type }` + Instruction for updating an existing file via the apply_patch tool. - A tool that allows the model to execute shell commands in a local environment. + - `diff: string` - - `type: "local_shell"` + Unified diff content to apply to the existing file. - The type of the local shell tool. Always `local_shell`. + - `path: string` - - `"local_shell"` + Path of the file to update relative to the workspace root. - - `Shell object { type, allowed_callers, environment }` + - `type: "update_file"` - A tool that allows the model to execute shell commands. + The operation type. Always `update_file`. - - `type: "shell"` + - `"update_file"` - The type of the shell tool. Always `shell`. + - `status: "in_progress" or "completed"` - - `"shell"` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"in_progress"` - The tool invocation context(s). + - `"completed"` - - `"direct"` + - `type: "apply_patch_call"` - - `"programmatic"` + The type of the item. Always `apply_patch_call`. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `"apply_patch_call"` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `id: optional string` - - `type: "container_auto"` + The unique ID of the apply patch tool call. Populated when this item is returned via API. - Automatically creates a container for this request + - `agent: optional object { agent_name }` - - `"container_auto"` + The agent that produced this item. - - `file_ids: optional array of string` + - `agent_name: string` - An optional list of uploaded files to make available to your code. + The canonical name of the agent that produced this item. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `caller: optional object { type } or object { caller_id, type }` - The memory limit for the container. + The execution context that produced this tool call. - - `"1g"` + - `Direct object { type }` - - `"4g"` + - `type: "direct"` - - `"16g"` + The caller type. Always `direct`. - - `"64g"` + - `"direct"` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `Program object { caller_id, type }` - Network access policy for the container. + - `caller_id: string` - - `BetaContainerNetworkPolicyDisabled object { type }` + The call ID of the program item that produced this tool call. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `type: "program"` - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + The caller type. Always `program`. - An optional list of skills referenced by id or inline data. + - `"program"` - - `BetaSkillReference object { skill_id, type, version }` + - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` - - `skill_id: string` + The streamed output emitted by an apply patch tool call. - The ID of the referenced skill. + - `call_id: string` - - `type: "skill_reference"` + The unique ID of the apply patch tool call generated by the model. - References a skill created with the /v1/skills endpoint. + - `status: "completed" or "failed"` - - `"skill_reference"` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `version: optional string` + - `"completed"` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `"failed"` - - `BetaInlineSkill object { description, name, source, type }` + - `type: "apply_patch_call_output"` - - `description: string` + The type of the item. Always `apply_patch_call_output`. - The description of the skill. + - `"apply_patch_call_output"` - - `name: string` + - `id: optional string` - The name of the skill. + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `source: BetaInlineSkillSource` + - `agent: optional object { agent_name }` - Inline skill payload + The agent that produced this item. - - `data: string` + - `agent_name: string` - Base64-encoded skill zip bundle. + The canonical name of the agent that produced this item. - - `media_type: "application/zip"` + - `caller: optional object { type } or object { caller_id, type }` - The media type of the inline skill payload. Must be `application/zip`. + The execution context that produced this tool call. - - `"application/zip"` + - `Direct object { type }` - - `type: "base64"` + - `type: "direct"` - The type of the inline skill source. Must be `base64`. + The caller type. Always `direct`. - - `"base64"` + - `"direct"` - - `type: "inline"` + - `Program object { caller_id, type }` - Defines an inline skill for this request. + - `caller_id: string` - - `"inline"` + The call ID of the program item that produced this tool call. - - `BetaLocalEnvironment object { type, skills }` + - `type: "program"` - - `type: "local"` + The caller type. Always `program`. - Use a local computer environment. + - `"program"` - - `"local"` + - `output: optional string` - - `skills: optional array of BetaLocalSkill` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - An optional list of skills. + - `McpListTools object { id, server_label, tools, 3 more }` - - `description: string` + A list of tools available on an MCP server. - The description of the skill. + - `id: string` - - `name: string` + The unique ID of the list. - The name of the skill. + - `server_label: string` - - `path: string` + The label of the MCP server. - The path to the directory containing the skill. + - `tools: array of object { input_schema, name, annotations, description }` - - `BetaContainerReference object { container_id, type }` + The tools available on the server. - - `container_id: string` + - `input_schema: unknown` - The ID of the referenced container. + The JSON schema describing the tool's input. - - `type: "container_reference"` + - `name: string` - References a container created with the /v1/containers endpoint + The name of the tool. - - `"container_reference"` + - `annotations: optional unknown` - - `Custom object { name, type, allowed_callers, 3 more }` + Additional annotations about the tool. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `description: optional string` - - `name: string` + The description of the tool. - The name of the custom tool, used to identify it in tool calls. + - `type: "mcp_list_tools"` - - `type: "custom"` + The type of the item. Always `mcp_list_tools`. - The type of the custom tool. Always `custom`. + - `"mcp_list_tools"` - - `"custom"` + - `agent: optional object { agent_name }` - - `allowed_callers: optional array of "direct" or "programmatic"` + The agent that produced this item. - The tool invocation context(s). + - `agent_name: string` - - `"direct"` + The canonical name of the agent that produced this item. - - `"programmatic"` + - `error: optional string` - - `defer_loading: optional boolean` + Error message if the server could not list tools. - Whether this tool should be deferred and discovered via tool search. + - `McpApprovalRequest object { id, arguments, name, 3 more }` - - `description: optional string` + A request for human approval of a tool invocation. - Optional description of the custom tool, used to provide more context. + - `id: string` - - `format: optional object { type } or object { definition, syntax, type }` + The unique ID of the approval request. - The input format for the custom tool. Default is unconstrained text. + - `arguments: string` - - `Text object { type }` + A JSON string of arguments for the tool. - Unconstrained free-form text. + - `name: string` - - `type: "text"` + The name of the tool to run. - Unconstrained text format. Always `text`. + - `server_label: string` - - `"text"` + The label of the MCP server making the request. - - `Grammar object { definition, syntax, type }` + - `type: "mcp_approval_request"` - A grammar defined by the user. + The type of the item. Always `mcp_approval_request`. - - `definition: string` + - `"mcp_approval_request"` - The grammar definition. + - `agent: optional object { agent_name }` - - `syntax: "lark" or "regex"` + The agent that produced this item. - The syntax of the grammar definition. One of `lark` or `regex`. + - `agent_name: string` - - `"lark"` + The canonical name of the agent that produced this item. - - `"regex"` + - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` - - `type: "grammar"` + A response to an MCP approval request. - Grammar format. Always `grammar`. + - `approval_request_id: string` - - `"grammar"` + The ID of the approval request being answered. - - `Namespace object { description, name, tools, type }` + - `approve: boolean` - Groups function/custom tools under a shared namespace. + Whether the request was approved. - - `description: string` + - `type: "mcp_approval_response"` - A description of the namespace shown to the model. + The type of the item. Always `mcp_approval_response`. - - `name: string` + - `"mcp_approval_response"` - The namespace name used in tool calls (for example, `crm`). + - `id: optional 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 response - The function/custom tools available inside this namespace. + - `agent: optional object { agent_name }` - - `Function object { name, type, allowed_callers, 5 more }` + The agent that produced this item. - - `name: string` + - `agent_name: string` - - `type: "function"` + The canonical name of the agent that produced this item. - - `"function"` + - `reason: optional string` - - `allowed_callers: optional array of "direct" or "programmatic"` + Optional reason for the decision. - The tool invocation context(s). + - `McpCall object { id, arguments, name, 7 more }` - - `"direct"` + An invocation of a tool on an MCP server. - - `"programmatic"` + - `id: string` - - `defer_loading: optional boolean` + The unique ID of the tool call. - Whether this function should be deferred and discovered via tool search. + - `arguments: string` - - `description: optional string` + A JSON string of the arguments passed to the tool. - - `output_schema: optional map[unknown]` + - `name: string` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + The name of the tool that was run. - - `parameters: optional unknown` + - `server_label: string` - - `strict: optional boolean` + The label of the MCP server running the tool. - 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: "mcp_call"` - - `Custom object { name, type, allowed_callers, 3 more }` + The type of the item. Always `mcp_call`. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `"mcp_call"` - - `name: string` + - `agent: optional object { agent_name }` - The name of the custom tool, used to identify it in tool calls. + The agent that produced this item. - - `type: "custom"` + - `agent_name: string` - The type of the custom tool. Always `custom`. + The canonical name of the agent that produced this item. - - `"custom"` + - `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 tool 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`. - Optional description of the custom tool, used to provide more context. + - `"in_progress"` - - `format: optional object { type } or object { definition, syntax, type }` + - `"completed"` - The input format for the custom tool. Default is unconstrained text. + - `"incomplete"` - - `Text object { type }` + - `"calling"` - Unconstrained free-form text. + - `"failed"` - - `type: "text"` + - `CustomToolCallOutput object { call_id, output, type, 3 more }` - Unconstrained text format. Always `text`. + The output of a custom tool call from your code, being sent back to the model. - - `"text"` + - `call_id: string` - - `Grammar object { definition, syntax, type }` + The call ID, used to map this custom tool call output to a custom tool call. - A grammar defined by the user. + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `definition: string` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - The grammar definition. + - `StringOutput = string` - - `syntax: "lark" or "regex"` + A string of the output of the custom tool call. - The syntax of the grammar definition. One of `lark` or `regex`. + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `"lark"` + Text, image, or file output of the custom tool call. - - `"regex"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `type: "grammar"` + A text input to the model. - Grammar format. Always `grammar`. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `"grammar"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `type: "namespace"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - The type of the tool. Always `namespace`. + A file input to the model. - - `"namespace"` + - `type: "custom_tool_call_output"` - - `ToolSearch object { type, description, execution, parameters }` + The type of the custom tool call output. Always `custom_tool_call_output`. - Hosted or BYOT tool search configuration for deferred tools. + - `"custom_tool_call_output"` - - `type: "tool_search"` + - `id: optional string` - The type of the tool. Always `tool_search`. + The unique ID of the custom tool call output in the OpenAI platform. - - `"tool_search"` + - `agent: optional object { agent_name }` - - `description: optional string` + The agent that produced this item. - Description shown to the model for a client-executed tool search tool. + - `agent_name: string` - - `execution: optional "server" or "client"` + The canonical name of the agent that produced this item. - Whether tool search is executed by the server or by the client. + - `caller: optional object { type } or object { caller_id, type }` - - `"server"` + The execution context that produced this tool call. - - `"client"` + - `Direct object { type }` - - `parameters: optional unknown` + - `type: "direct"` - Parameter schema for a client-executed tool search tool. + The caller type. Always `direct`. - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `"direct"` - 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). + - `Program object { caller_id, type }` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `caller_id: string` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + The call ID of the program item that produced this tool call. - - `"web_search_preview"` + - `type: "program"` - - `"web_search_preview_2025_03_11"` + The caller type. Always `program`. - - `search_content_types: optional array of "text" or "image"` + - `"program"` - - `"text"` + - `CustomToolCall object { call_id, input, name, 5 more }` - - `"image"` + A call to a custom tool created by the model. - - `search_context_size: optional "low" or "medium" or "high"` + - `call_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. + An identifier used to map this custom tool call to a tool call output. - - `"low"` + - `input: string` - - `"medium"` + The input for the custom tool call generated by the model. - - `"high"` + - `name: string` - - `user_location: optional object { type, city, country, 2 more }` + The name of the custom tool being called. - The user's location. + - `type: "custom_tool_call"` - - `type: "approximate"` + The type of the custom tool call. Always `custom_tool_call`. - The type of location approximation. Always `approximate`. + - `"custom_tool_call"` - - `"approximate"` + - `id: optional string` - - `city: optional string` + The unique ID of the custom tool call in the OpenAI platform. - Free text input for the city of the user, e.g. `San Francisco`. + - `agent: optional object { agent_name }` - - `country: optional string` + The agent that produced this item. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `agent_name: string` - - `region: optional string` + The canonical name of the agent that produced this item. - Free text input for the region of the user, e.g. `California`. + - `caller: optional object { type } or object { caller_id, type }` - - `timezone: optional string` + The execution context that produced this tool call. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `Direct object { type }` - - `ApplyPatch object { type, allowed_callers }` + - `type: "direct"` - Allows the assistant to create, delete, or update files using unified diffs. + - `"direct"` - - `type: "apply_patch"` + - `Program object { caller_id, type }` - The type of the tool. Always `apply_patch`. + - `caller_id: string` - - `"apply_patch"` + The call ID of the program item that produced this tool call. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "program"` - The tool invocation context(s). + - `"program"` - - `"direct"` + - `namespace: optional string` - - `"programmatic"` + The namespace of the custom tool being called. - - `type: "tool_search_output"` + - `CompactionTrigger object { type, agent }` - The item type. Always `tool_search_output`. + Compacts the current context. Must be the final input item. - - `"tool_search_output"` + - `type: "compaction_trigger"` - - `id: optional string` + The type of the item. Always `compaction_trigger`. - The unique ID of this tool search output. + - `"compaction_trigger"` - `agent: optional object { agent_name }` @@ -161441,1038 +160401,1028 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `call_id: optional string` + - `ItemReference object { id, agent, type }` - The unique ID of the tool search call generated by the model. + An internal identifier for an item to reference. - - `execution: optional "server" or "client"` + - `id: string` - Whether tool search was executed by the server or by the client. + The ID of the item to reference. - - `"server"` + - `agent: optional object { agent_name }` - - `"client"` + The agent that produced this item. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `agent_name: string` - The status of the tool search output. + The canonical name of the agent that produced this item. - - `"in_progress"` + - `type: optional "item_reference"` - - `"completed"` + The type of item to reference. Always `item_reference`. - - `"incomplete"` + - `"item_reference"` - - `AdditionalTools object { role, tools, type, 2 more }` + - `Program object { id, call_id, code, 3 more }` - - `role: "developer"` + - `id: string` - The role that provided the additional tools. Only `developer` is supported. + The unique ID of this program item. - - `"developer"` + - `call_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 stable call ID of the program item. - A list of additional tools made available at this item. + - `code: string` - - `Function object { name, parameters, strict, 5 more }` + The JavaScript source executed by programmatic tool calling. - 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). + - `fingerprint: string` - - `name: string` + Opaque program replay fingerprint that must be round-tripped. - The name of the function to call. + - `type: "program"` - - `parameters: map[unknown]` + The item type. Always `program`. - A JSON schema object describing the parameters of the function. + - `"program"` - - `strict: boolean` + - `agent: optional object { agent_name }` - Whether strict parameter validation is enforced for this function tool. + The agent that produced this item. - - `type: "function"` + - `agent_name: string` - The type of the function tool. Always `function`. + The canonical name of the agent that produced this item. - - `"function"` + - `ProgramOutput object { id, call_id, result, 3 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `id: string` - The tool invocation context(s). + The unique ID of this program output item. - - `"direct"` + - `call_id: string` - - `"programmatic"` + The call ID of the program item. - - `defer_loading: optional boolean` + - `result: string` - Whether this function is deferred and loaded via tool search. + The result produced by the program item. - - `description: optional string` + - `status: "completed" or "incomplete"` - A description of the function. Used by the model to determine whether or not to call the function. + The terminal status of the program output. - - `output_schema: optional map[unknown]` + - `"completed"` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `"incomplete"` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `type: "program_output"` - 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 item type. Always `program_output`. - - `type: "file_search"` + - `"program_output"` - The type of the file search tool. Always `file_search`. + - `agent: optional object { agent_name }` - - `"file_search"` + The agent that produced this item. - - `vector_store_ids: array of string` + - `agent_name: string` - The IDs of the vector stores to search. + The canonical name of the agent that produced this item. - - `filters: optional object { key, type, value } or object { filters, type }` + - `metadata: map[string]` - A filter to apply. + 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. - - `ComparisonFilter object { key, type, value }` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - - `key: string` + 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. - The key to compare against the value. + - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` - - `type: "eq" or "ne" or "gt" or 5 more` + 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. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"gpt-5.6-sol"` - - `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 + - `"gpt-5.6-terra"` - - `"eq"` + - `"gpt-5.6-luna"` - - `"ne"` + - `"gpt-5.4"` - - `"gt"` + - `"gpt-5.4-mini"` - - `"gte"` + - `"gpt-5.4-nano"` - - `"lt"` + - `"gpt-5.4-mini-2026-03-17"` - - `"lte"` + - `"gpt-5.4-nano-2026-03-17"` - - `"in"` + - `"gpt-5.3-chat-latest"` - - `"nin"` + - `"gpt-5.2"` - - `value: string or number or boolean or array of string or number` + - `"gpt-5.2-2025-12-11"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `"gpt-5.2-chat-latest"` - - `string` + - `"gpt-5.2-pro"` - - `number` + - `"gpt-5.2-pro-2025-12-11"` - - `boolean` + - `"gpt-5.1"` - - `array of string or number` + - `"gpt-5.1-2025-11-13"` - - `string` + - `"gpt-5.1-codex"` - - `number` + - `"gpt-5.1-mini"` - - `CompoundFilter object { filters, type }` + - `"gpt-5.1-chat-latest"` - Combine multiple filters using `and` or `or`. + - `"gpt-5"` - - `filters: array of object { key, type, value } or unknown` + - `"gpt-5-mini"` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `"gpt-5-nano"` - - `ComparisonFilter object { key, type, value }` + - `"gpt-5-2025-08-07"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"gpt-5-mini-2025-08-07"` - - `key: string` + - `"gpt-5-nano-2025-08-07"` - The key to compare against the value. + - `"gpt-5-chat-latest"` - - `type: "eq" or "ne" or "gt" or 5 more` + - `"gpt-4.1"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"gpt-4.1-mini"` - - `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 + - `"gpt-4.1-nano"` - - `"eq"` + - `"gpt-4.1-2025-04-14"` - - `"ne"` + - `"gpt-4.1-mini-2025-04-14"` - - `"gt"` + - `"gpt-4.1-nano-2025-04-14"` - - `"gte"` + - `"o4-mini"` - - `"lt"` + - `"o4-mini-2025-04-16"` - - `"lte"` + - `"o3"` - - `"in"` + - `"o3-2025-04-16"` - - `"nin"` + - `"o3-mini"` - - `value: string or number or boolean or array of string or number` + - `"o3-mini-2025-01-31"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `"o1"` - - `string` + - `"o1-2024-12-17"` - - `number` + - `"o1-preview"` - - `boolean` + - `"o1-preview-2024-09-12"` - - `array of string or number` + - `"o1-mini"` - - `string` + - `"o1-mini-2024-09-12"` - - `number` + - `"gpt-4o"` - - `unknown` + - `"gpt-4o-2024-11-20"` - - `type: "and" or "or"` + - `"gpt-4o-2024-08-06"` - Type of operation: `and` or `or`. + - `"gpt-4o-2024-05-13"` - - `"and"` + - `"gpt-4o-audio-preview"` - - `"or"` + - `"gpt-4o-audio-preview-2024-10-01"` - - `max_num_results: optional number` + - `"gpt-4o-audio-preview-2024-12-17"` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `"gpt-4o-audio-preview-2025-06-03"` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `"gpt-4o-mini-audio-preview"` - Ranking options for search. + - `"gpt-4o-mini-audio-preview-2024-12-17"` - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `"gpt-4o-search-preview"` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `"gpt-4o-mini-search-preview"` - - `embedding_weight: number` + - `"gpt-4o-search-preview-2025-03-11"` - The weight of the embedding in the reciprocal ranking fusion. + - `"gpt-4o-mini-search-preview-2025-03-11"` - - `text_weight: number` + - `"chatgpt-4o-latest"` - The weight of the text in the reciprocal ranking fusion. + - `"codex-mini-latest"` - - `ranker: optional "auto" or "default-2024-11-15"` + - `"gpt-4o-mini"` - The ranker to use for the file search. + - `"gpt-4o-mini-2024-07-18"` - - `"auto"` + - `"gpt-4-turbo"` - - `"default-2024-11-15"` + - `"gpt-4-turbo-2024-04-09"` - - `score_threshold: optional number` + - `"gpt-4-0125-preview"` - 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. + - `"gpt-4-turbo-preview"` - - `Computer object { type }` + - `"gpt-4-1106-preview"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"gpt-4-vision-preview"` - - `type: "computer"` + - `"gpt-4"` - The type of the computer tool. Always `computer`. + - `"gpt-4-0314"` - - `"computer"` + - `"gpt-4-0613"` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `"gpt-4-32k"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"gpt-4-32k-0314"` - - `display_height: number` + - `"gpt-4-32k-0613"` - The height of the computer display. + - `"gpt-3.5-turbo"` - - `display_width: number` + - `"gpt-3.5-turbo-16k"` - The width of the computer display. + - `"gpt-3.5-turbo-0301"` - - `environment: "windows" or "mac" or "linux" or 2 more` + - `"gpt-3.5-turbo-0613"` - The type of computer environment to control. + - `"gpt-3.5-turbo-1106"` - - `"windows"` + - `"gpt-3.5-turbo-0125"` - - `"mac"` + - `"gpt-3.5-turbo-16k-0613"` - - `"linux"` + - `"o1-pro"` - - `"ubuntu"` + - `"o1-pro-2025-03-19"` - - `"browser"` + - `"o3-pro"` - - `type: "computer_use_preview"` + - `"o3-pro-2025-06-10"` - The type of the computer use tool. Always `computer_use_preview`. + - `"o3-deep-research"` - - `"computer_use_preview"` + - `"o3-deep-research-2025-06-26"` - - `WebSearch object { type, filters, search_context_size, user_location }` + - `"o4-mini-deep-research"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + - `"o4-mini-deep-research-2025-06-26"` - - `type: "web_search" or "web_search_2025_08_26"` + - `"computer-use-preview"` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `"computer-use-preview-2025-03-11"` - - `"web_search"` + - `"gpt-5-codex"` - - `"web_search_2025_08_26"` + - `"gpt-5-pro"` - - `filters: optional object { allowed_domains }` + - `"gpt-5-pro-2025-10-06"` - Filters for the search. + - `"gpt-5.1-codex-max"` - - `allowed_domains: optional array of string` + - `string` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `object: "response"` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The object type of this resource - always set to `response`. - - `search_context_size: optional "low" or "medium" or "high"` + - `"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. + - `output: array of BetaResponseOutputItem` - - `"low"` + An array of content items generated by the model. - - `"medium"` + - 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. - - `"high"` + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - - `user_location: optional object { city, country, region, 2 more }` + An output message from the model. - The approximate location of the user. + - `FileSearchCall object { id, queries, status, 3 more }` - - `city: optional string` + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - Free text input for the city of the user, e.g. `San Francisco`. + - `id: string` - - `country: optional string` + The unique ID of the file search tool call. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `queries: array of string` - - `region: optional string` + The queries used to search for files. - Free text input for the region of the user, e.g. `California`. + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `timezone: optional string` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `"in_progress"` - - `type: optional "approximate"` + - `"searching"` - The type of location approximation. Always `approximate`. + - `"completed"` - - `"approximate"` + - `"incomplete"` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `"failed"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + - `type: "file_search_call"` - - `server_label: string` + The type of the file search tool call. Always `file_search_call`. - A label for this MCP server, used to identify it in tool calls. + - `"file_search_call"` - - `type: "mcp"` + - `agent: optional object { agent_name }` - The type of the MCP tool. Always `mcp`. + The agent that produced this item. - - `"mcp"` + - `agent_name: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The canonical name of the agent that produced this item. - The tool invocation context(s). + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `"direct"` + The results of the file search tool call. - - `"programmatic"` + - `attributes: optional map[string or number or boolean]` - - `allowed_tools: optional array of string or object { read_only, 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. - List of allowed tool names or a filter object. + - `string` - - `McpAllowedTools = array of string` + - `number` - A string array of allowed tool names + - `boolean` - - `McpToolFilter object { read_only, tool_names }` + - `file_id: optional string` - A filter object to specify which tools are allowed. + The unique ID of the file. - - `read_only: optional boolean` + - `filename: 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 name of the file. - - `tool_names: optional array of string` + - `score: optional number` - List of allowed tool names. + The relevance score of the file - a value between 0 and 1. - - `authorization: optional string` + - `text: optional string` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + The text that was retrieved from the file. - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `FunctionCall object { arguments, call_id, name, 6 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 tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - Currently supported `connector_id` values are: + - `arguments: 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` + A JSON string of the arguments to pass to the function. - - `"connector_dropbox"` + - `call_id: string` - - `"connector_gmail"` + The unique ID of the function tool call generated by the model. - - `"connector_googlecalendar"` + - `name: string` - - `"connector_googledrive"` + The name of the function to run. - - `"connector_microsoftteams"` + - `type: "function_call"` - - `"connector_outlookcalendar"` + The type of the function tool call. Always `function_call`. - - `"connector_outlookemail"` + - `"function_call"` - - `"connector_sharepoint"` + - `id: optional string` - - `defer_loading: optional boolean` + The unique ID of the function tool call. - Whether this MCP tool is deferred and discovered via tool search. + - `agent: optional object { agent_name }` - - `headers: optional map[string]` + The agent that produced this item. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `agent_name: string` - - `require_approval: optional object { always, never } or "always" or "never"` + The canonical name of the agent that produced this item. - Specify which of the MCP server's tools require approval. + - `caller: optional object { type } or object { caller_id, type }` - - `McpToolApprovalFilter object { always, never }` + The execution context that produced this tool call. - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `Direct object { type }` - - `always: optional 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"` - - `never: optional object { read_only, tool_names }` + - `"program"` - A filter object to specify which tools are allowed. + - `namespace: optional string` - - `read_only: optional boolean` + The namespace of the function to run. - 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 item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - List of allowed tool names. + - `"in_progress"` - - `McpToolApprovalSetting = "always" or "never"` + - `"completed"` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `"incomplete"` - - `"always"` + - `FunctionCallOutput object { id, call_id, output, 5 more }` - - `"never"` + - `id: string` - - `server_description: optional string` + The unique ID of the function call tool output. - Optional description of the MCP server, used to provide more context. + - `call_id: string` - - `server_url: optional string` + The unique ID of the function tool call generated by the model. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `tunnel_id: optional string` + The output from the function call generated by your code. + Can be a string or an list of output content. - 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. + - `StringOutput = string` - - `CodeInterpreter object { container, type, allowed_callers }` + A string of the output of the function call. - A tool that runs Python code to help generate a response to a prompt. + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + Text, image, or file output of the function call. - 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. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `string` + A text input to the model. - The container ID. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `type: "auto"` + A file input to the model. - Always `auto`. + - `status: "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. - - `file_ids: optional array of string` + - `"in_progress"` - An optional list of uploaded files to make available to your code. + - `"completed"` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `"incomplete"` - The memory limit for the code interpreter container. + - `type: "function_call_output"` - - `"1g"` + The type of the function tool call output. Always `function_call_output`. - - `"4g"` + - `"function_call_output"` - - `"16g"` + - `agent: optional object { agent_name }` - - `"64g"` + The agent that produced this item. - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `agent_name: string` - Network access policy for the container. + The canonical name of the agent that produced this item. - - `BetaContainerNetworkPolicyDisabled object { type }` + - `caller: optional object { type } or object { caller_id, type }` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + The execution context that produced this tool call. - - `type: "code_interpreter"` + - `Direct object { type }` - The type of the code interpreter tool. Always `code_interpreter`. + - `type: "direct"` - - `"code_interpreter"` + The caller type. Always `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. - - `ProgrammaticToolCalling object { type }` + - `type: "program"` - - `type: "programmatic_tool_calling"` + The caller type. Always `program`. - The type of the tool. Always `programmatic_tool_calling`. + - `"program"` - - `"programmatic_tool_calling"` + - `created_by: optional string` - - `ImageGeneration object { type, action, background, 9 more }` + The identifier of the actor that created the item. - A tool that generates images using the GPT image models. + - `AgentMessage object { id, author, content, 3 more }` - - `type: "image_generation"` + - `id: string` - The type of the image generation tool. Always `image_generation`. + The unique ID of the agent message. - - `"image_generation"` + - `author: string` - - `action: optional "generate" or "edit" or "auto"` + The sending agent identity. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - - `"generate"` + Encrypted content sent between agents. - - `"edit"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `"auto"` + A text input to the model. - - `background: optional "transparent" or "opaque" or "auto"` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + A text output from the model. - - `"transparent"` + - `Text object { text, type }` - - `"opaque"` + A text content. - - `"auto"` + - `text: string` - - `input_fidelity: optional "high" or "low"` + - `type: "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`. + - `"text"` - - `"high"` + - `SummaryText object { text, type }` - - `"low"` + A summary 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). + A summary of the reasoning output from the model so far. - - `file_id: optional string` + - `type: "summary_text"` - File ID for the mask image. + The type of the object. Always `summary_text`. - - `image_url: optional string` + - `"summary_text"` - Base64-encoded mask image. + - `ReasoningText object { text, type }` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + Reasoning text from the model. - The image generation model to use. Default: `gpt-image-1`. + - `text: string` - - `string` + The reasoning text from the model. - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `type: "reasoning_text"` - The image generation model to use. Default: `gpt-image-1`. + The type of the reasoning text. Always `reasoning_text`. - - `"gpt-image-1"` + - `"reasoning_text"` - - `"gpt-image-1-mini"` + - `BetaResponseOutputRefusal object { refusal, type }` - - `"gpt-image-1.5"` + A refusal from the model. - - `moderation: optional "auto" or "low"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - Moderation level for the generated image. Default: `auto`. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"auto"` + - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` + + A screenshot of a computer. + + - `detail: "low" or "high" or "auto" or "original"` + + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - `"low"` - - `output_compression: optional number` + - `"high"` - Compression level for the output image. Default: 100. + - `"auto"` - - `output_format: optional "png" or "webp" or "jpeg"` + - `"original"` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `file_id: string` - - `"png"` + The identifier of an uploaded file that contains the screenshot. - - `"webp"` + - `image_url: string` - - `"jpeg"` + The URL of the screenshot image. - - `partial_images: optional number` + - `type: "computer_screenshot"` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `"computer_screenshot"` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `prompt_cache_breakpoint: optional object { mode }` - - `"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. - - `"medium"` + - `mode: "explicit"` - - `"high"` + The breakpoint mode. Always `explicit`. - - `"auto"` + - `"explicit"` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + A file input to the model. - - `string` + - `EncryptedContent object { encrypted_content, type }` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - 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`. + - `encrypted_content: string` - - `"1024x1024"` + Opaque encrypted content. - - `"1024x1536"` + - `type: "encrypted_content"` - - `"1536x1024"` + The type of the input item. Always `encrypted_content`. - - `"auto"` + - `"encrypted_content"` - - `LocalShell object { type }` + - `recipient: string` - A tool that allows the model to execute shell commands in a local environment. + The destination agent identity. - - `type: "local_shell"` + - `type: "agent_message"` - The type of the local shell tool. Always `local_shell`. + The type of the item. Always `agent_message`. - - `"local_shell"` + - `"agent_message"` - - `Shell object { type, allowed_callers, environment }` + - `agent: optional object { agent_name }` - A tool that allows the model to execute shell commands. + The agent that produced this item. - - `type: "shell"` + - `agent_name: string` - The type of the shell tool. Always `shell`. + The canonical name of the agent that produced this item. - - `"shell"` + - `MultiAgentCall object { id, action, arguments, 3 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `id: string` - The tool invocation context(s). + The unique ID of the multi-agent call item. - - `"direct"` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `"programmatic"` + The multi-agent action to execute. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `"spawn_agent"` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `"interrupt_agent"` - - `BetaLocalEnvironment object { type, skills }` + - `"list_agents"` - - `BetaContainerReference object { container_id, type }` + - `"send_message"` - - `Custom object { name, type, allowed_callers, 3 more }` + - `"followup_task"` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `"wait_agent"` - - `name: string` + - `arguments: string` - The name of the custom tool, used to identify it in tool calls. + The JSON string of arguments generated for the action. - - `type: "custom"` + - `call_id: string` - The type of the custom tool. Always `custom`. + The unique ID linking this call to its output. - - `"custom"` + - `type: "multi_agent_call"` - - `allowed_callers: optional array of "direct" or "programmatic"` + The type of the multi-agent call. Always `multi_agent_call`. - The tool invocation context(s). + - `"multi_agent_call"` - - `"direct"` + - `agent: optional object { agent_name }` - - `"programmatic"` + The agent that produced this item. - - `defer_loading: optional boolean` + - `agent_name: string` - Whether this tool should be deferred and discovered via tool search. + The canonical name of the agent that produced this item. - - `description: optional string` + - `MultiAgentCallOutput object { id, action, call_id, 3 more }` - Optional description of the custom tool, used to provide more context. + - `id: string` - - `format: optional object { type } or object { definition, syntax, type }` + The unique ID of the multi-agent call output item. - The input format for the custom tool. Default is unconstrained text. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `Text object { type }` + The multi-agent action that produced this result. - Unconstrained free-form text. + - `"spawn_agent"` - - `type: "text"` + - `"interrupt_agent"` - Unconstrained text format. Always `text`. + - `"list_agents"` - - `"text"` + - `"send_message"` - - `Grammar object { definition, syntax, type }` + - `"followup_task"` - A grammar defined by the user. + - `"wait_agent"` - - `definition: string` + - `call_id: string` - The grammar definition. + The unique ID of the multi-agent call. - - `syntax: "lark" or "regex"` + - `output: array of BetaResponseOutputText` - The syntax of the grammar definition. One of `lark` or `regex`. + Text output returned by the multi-agent action. - - `"lark"` + - `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 }` - - `"regex"` + The annotations of the text output. - - `type: "grammar"` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - Grammar format. Always `grammar`. + - `text: string` - - `"grammar"` + The text output from the model. - - `Namespace object { description, name, tools, type }` + - `type: "output_text"` - Groups function/custom tools under a shared namespace. + The type of the output text. Always `output_text`. - - `description: string` + - `type: "multi_agent_call_output"` - A description of the namespace shown to the model. + The type of the multi-agent result. Always `multi_agent_call_output`. - - `name: string` + - `"multi_agent_call_output"` - The namespace name used in tool calls (for example, `crm`). + - `agent: optional object { agent_name }` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + The agent that produced this item. - The function/custom tools available inside this namespace. + - `agent_name: string` - - `Function object { name, type, allowed_callers, 5 more }` + The canonical name of the agent that produced this item. - - `name: string` + - `WebSearchCall object { id, action, status, 2 more }` - - `type: "function"` + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `"function"` + - `id: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The unique ID of the web search tool call. - The tool invocation context(s). + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `"direct"` + 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). - - `"programmatic"` + - `Search object { type, queries, query, sources }` - - `defer_loading: optional boolean` + Action type "search" - Performs a web search query. - Whether this function should be deferred and discovered via tool search. + - `type: "search"` - - `description: optional string` + The action type. - - `output_schema: optional map[unknown]` + - `"search"` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `queries: optional array of string` - - `parameters: optional unknown` + The search queries. - - `strict: optional boolean` + - `query: optional string` - 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 search query. - - `Custom object { name, type, allowed_callers, 3 more }` + - `sources: optional array of object { type, url }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + The sources used in the search. - - `name: string` + - `type: "url"` - The name of the custom tool, used to identify it in tool calls. + The type of source. Always `url`. - - `type: "custom"` + - `"url"` - The type of the custom tool. Always `custom`. + - `url: string` - - `"custom"` + The URL of the source. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `OpenPage object { type, url }` - The tool invocation context(s). + Action type "open_page" - Opens a specific URL from search results. - - `"direct"` + - `type: "open_page"` - - `"programmatic"` + The action type. - - `defer_loading: optional boolean` + - `"open_page"` - Whether this tool should be deferred and discovered via tool search. + - `url: optional string` - - `description: optional string` + The URL opened by the model. - Optional description of the custom tool, used to provide more context. + - `FindInPage object { pattern, type, url }` - - `format: optional object { type } or object { definition, syntax, type }` + Action type "find_in_page": Searches for a pattern within a loaded page. - The input format for the custom tool. Default is unconstrained text. + - `pattern: string` - - `Text object { type }` + The pattern or text to search for within the page. - Unconstrained free-form text. + - `type: "find_in_page"` - - `type: "text"` + The action type. - Unconstrained text format. Always `text`. + - `"find_in_page"` - - `"text"` + - `url: string` - - `Grammar object { definition, syntax, type }` + The URL of the page searched for the pattern. - A grammar defined by the user. + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `definition: string` + The status of the web search tool call. - The grammar definition. + - `"in_progress"` - - `syntax: "lark" or "regex"` + - `"searching"` - The syntax of the grammar definition. One of `lark` or `regex`. + - `"completed"` - - `"lark"` + - `"failed"` - - `"regex"` + - `type: "web_search_call"` - - `type: "grammar"` + The type of the web search tool call. Always `web_search_call`. - Grammar format. Always `grammar`. + - `"web_search_call"` - - `"grammar"` + - `agent: optional object { agent_name }` - - `type: "namespace"` + The agent that produced this item. - The type of the tool. Always `namespace`. + - `agent_name: string` - - `"namespace"` + The canonical name of the agent that produced this item. - - `ToolSearch object { type, description, execution, parameters }` + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - Hosted or BYOT tool search configuration for deferred tools. + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - - `type: "tool_search"` + - `id: string` - The type of the tool. Always `tool_search`. + The unique ID of the computer call. - - `"tool_search"` + - `call_id: string` - - `description: optional string` + An identifier used when responding to the tool call with output. - Description shown to the model for a client-executed tool search tool. + - `pending_safety_checks: array of object { id, code, message }` - - `execution: optional "server" or "client"` + The pending safety checks for the computer call. - Whether tool search is executed by the server or by the client. + - `id: string` - - `"server"` + The ID of the pending safety check. - - `"client"` + - `code: optional string` - - `parameters: optional unknown` + The type of the pending safety check. - Parameter schema for a client-executed tool search tool. + - `message: optional string` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + Details about the pending safety check. - 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). + - `status: "in_progress" or "completed" or "incomplete"` - - `type: "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. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `"in_progress"` - - `"web_search_preview"` + - `"completed"` - - `"web_search_preview_2025_03_11"` + - `"incomplete"` - - `search_content_types: optional array of "text" or "image"` + - `type: "computer_call"` - - `"text"` + The type of the computer call. Always `computer_call`. - - `"image"` + - `"computer_call"` - - `search_context_size: optional "low" or "medium" or "high"` + - `action: optional BetaComputerAction` - 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 click action. - - `"low"` + - `actions: optional BetaComputerActionList` - - `"medium"` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `"high"` + - `agent: optional object { agent_name }` - - `user_location: optional object { type, city, country, 2 more }` + The agent that produced this item. - The user's location. + - `agent_name: string` - - `type: "approximate"` + The canonical name of the agent that produced this item. - The type of location approximation. Always `approximate`. + - `ComputerCallOutput object { id, call_id, output, 5 more }` - - `"approximate"` + - `id: string` - - `city: optional string` + The unique ID of the computer call tool output. - Free text input for the city of the user, e.g. `San Francisco`. + - `call_id: string` - - `country: optional string` + The ID of the computer tool call that produced the output. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `region: optional string` + A computer screenshot image used with the computer use tool. - Free text input for the region of the user, e.g. `California`. + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - - `timezone: optional string` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - 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. + - `"failed"` - - `type: "apply_patch"` + - `"in_progress"` - The type of the tool. Always `apply_patch`. + - `type: "computer_call_output"` - - `"apply_patch"` + The type of the computer tool call output. Always `computer_call_output`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"computer_call_output"` - The tool invocation context(s). + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `"direct"` + The safety checks reported by the API that have been acknowledged by the + developer. - - `"programmatic"` + - `id: string` - - `type: "additional_tools"` + The ID of the pending safety check. - The item type. Always `additional_tools`. + - `code: optional string` - - `"additional_tools"` + The type of the pending safety check. - - `id: optional string` + - `message: optional string` - The unique ID of this additional tools item. + Details about the pending safety check. - `agent: optional object { agent_name }` @@ -162482,6 +161432,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. + - `created_by: optional string` + + The identifier of the actor that created the item. + - `Reasoning object { id, summary, type, 4 more }` A description of the chain of thought used by a reasoning model while generating @@ -162552,23 +161506,29 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `Compaction object { encrypted_content, type, id, agent }` + - `Program object { id, call_id, code, 3 more }` - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + - `id: string` - - `encrypted_content: string` + The unique ID of the program item. - The encrypted content of the compaction summary. + - `call_id: string` - - `type: "compaction"` + The stable call ID of the program item. - The type of the item. Always `compaction`. + - `code: string` - - `"compaction"` + The JavaScript source executed by programmatic tool calling. - - `id: optional string` + - `fingerprint: string` - The ID of the compaction item. + Opaque program replay fingerprint that must be round-tripped. + + - `type: "program"` + + The type of the item. Always `program`. + + - `"program"` - `agent: optional object { agent_name }` @@ -162578,35 +161538,33 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `ImageGenerationCall object { id, result, status, 2 more }` - - An image generation request made by the model. + - `ProgramOutput object { id, call_id, result, 3 more }` - `id: string` - The unique ID of the image generation call. + The unique ID of the program output item. - - `result: string` + - `call_id: string` - The generated image encoded in base64. + The call ID of the program item. - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `result: string` - The status of the image generation call. + The result produced by the program item. - - `"in_progress"` + - `status: "completed" or "incomplete"` - - `"completed"` + The terminal status of the program output item. - - `"generating"` + - `"completed"` - - `"failed"` + - `"incomplete"` - - `type: "image_generation_call"` + - `type: "program_output"` - The type of the image generation call. Always `image_generation_call`. + The type of the item. Always `program_output`. - - `"image_generation_call"` + - `"program_output"` - `agent: optional object { agent_name }` @@ -162616,58 +161574,77 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `CodeInterpreterCall object { id, code, container_id, 4 more }` - - A tool call to run code. + - `ToolSearchCall object { id, arguments, call_id, 5 more }` - `id: string` - The unique ID of the code interpreter tool call. + The unique ID of the tool search call item. - - `code: string` + - `arguments: unknown` - The code to run, or null if not available. + Arguments used for the tool search call. - - `container_id: string` + - `call_id: string` - The ID of the container used to run the code. + The unique ID of the tool search call generated by the model. - - `outputs: array of object { logs, type } or object { type, url }` + - `execution: "server" or "client"` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + Whether tool search was executed by the server or by the client. - - `Logs object { logs, type }` + - `"server"` - The logs output from the code interpreter. + - `"client"` - - `logs: string` + - `status: "in_progress" or "completed" or "incomplete"` - The logs output from the code interpreter. + The status of the tool search call item that was recorded. - - `type: "logs"` + - `"in_progress"` - The type of the output. Always `logs`. + - `"completed"` - - `"logs"` + - `"incomplete"` - - `Image object { type, url }` + - `type: "tool_search_call"` - The image output from the code interpreter. + The type of the item. Always `tool_search_call`. - - `type: "image"` + - `"tool_search_call"` - The type of the output. Always `image`. + - `agent: optional object { agent_name }` - - `"image"` + The agent that produced this item. - - `url: string` + - `agent_name: string` - The URL of the image output from the code interpreter. + The canonical name of the agent that produced this item. - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `created_by: optional string` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + The identifier of the actor that created the item. + + - `ToolSearchOutput object { id, call_id, execution, 5 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"` @@ -162675,1946 +161652,2041 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `"interpreting"` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - - `"failed"` + The loaded tool definitions returned by tool search. - - `type: "code_interpreter_call"` + - `Function object { name, parameters, strict, 5 more }` - The type of the code interpreter tool call. Always `code_interpreter_call`. + 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). - - `"code_interpreter_call"` + - `name: string` - - `agent: optional object { agent_name }` + The name of the function to call. - The agent that produced this item. + - `parameters: map[unknown]` - - `agent_name: string` + A JSON schema object describing the parameters of the function. - The canonical name of the agent that produced this item. + - `strict: boolean` - - `LocalShellCall object { id, action, call_id, 3 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 object { key, type, value } or object { filters, type }` - 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"` + - `key: string` - - `type: "local_shell_call"` + The key to compare against the value. - The type of the local shell call. Always `local_shell_call`. + - `type: "eq" or "ne" or "gt" or 5 more` - - `"local_shell_call"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `agent: optional object { agent_name }` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - The agent that produced this item. + - `"eq"` - - `agent_name: string` + - `"ne"` - The canonical name of the agent that produced this item. + - `"gt"` - - `LocalShellCallOutput object { id, output, type, 2 more }` + - `"gte"` - The output of a local shell tool call. + - `"lt"` - - `id: string` + - `"lte"` - The unique ID of the local shell tool call generated by the model. + - `"in"` - - `output: string` + - `"nin"` - A JSON string of the output of the local shell tool call. + - `value: string or number or boolean or array of string or number` - - `type: "local_shell_call_output"` + The value to compare against the attribute key; supports string, number, or boolean types. - The type of the local shell tool call output. Always `local_shell_call_output`. + - `string` - - `"local_shell_call_output"` + - `number` - - `agent: optional object { agent_name }` + - `boolean` - The agent that produced this item. + - `array of string or number` - - `agent_name: string` + - `string` - The canonical name of the agent that produced this item. + - `number` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `CompoundFilter object { filters, type }` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + Combine multiple filters using `and` or `or`. - - `"in_progress"` + - `filters: array of object { key, type, value } or unknown` - - `"completed"` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `"incomplete"` + - `ComparisonFilter object { key, type, value }` - - `ShellCall object { action, call_id, type, 5 more }` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - A tool representing a request to execute one or more shell commands. + - `key: string` - - `action: object { commands, max_output_length, timeout_ms }` + The key to compare against the value. - The shell commands and limits that describe how to run the tool call. + - `type: "eq" or "ne" or "gt" or 5 more` - - `commands: array of string` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - Ordered shell commands for the execution environment to run. + - `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 - - `max_output_length: optional number` + - `"eq"` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `"ne"` - - `timeout_ms: optional number` + - `"gt"` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `"gte"` - - `call_id: string` + - `"lt"` - The unique ID of the shell tool call generated by the model. + - `"lte"` - - `type: "shell_call"` + - `"in"` - The type of the item. Always `shell_call`. + - `"nin"` - - `"shell_call"` + - `value: string or number or boolean or array of string or number` - - `id: optional string` + The value to compare against the attribute key; supports string, number, or boolean types. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `string` - - `agent: optional object { agent_name }` + - `number` - The agent that produced this item. + - `boolean` - - `agent_name: string` + - `array of string or number` - The canonical name of the agent that produced this item. + - `string` - - `caller: optional object { type } or object { caller_id, type }` + - `number` - The execution context that produced this tool call. + - `unknown` - - `Direct object { type }` + - `type: "and" or "or"` - - `type: "direct"` + Type of operation: `and` or `or`. - The caller type. Always `direct`. + - `"and"` - - `"direct"` + - `"or"` - - `Program object { caller_id, type }` + - `max_num_results: optional number` - - `caller_id: string` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - The call ID of the program item that produced this tool call. + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `type: "program"` + Ranking options for search. - The caller type. Always `program`. + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `"program"` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `environment: optional BetaLocalEnvironment or BetaContainerReference` + - `embedding_weight: number` - The environment to execute the shell commands in. + The weight of the embedding in the reciprocal ranking fusion. - - `BetaLocalEnvironment object { type, skills }` + - `text_weight: number` - - `BetaContainerReference object { container_id, type }` + The weight of the text in the reciprocal ranking fusion. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `ranker: optional "auto" or "default-2024-11-15"` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + The ranker to use for the file search. - - `"in_progress"` + - `"auto"` - - `"completed"` + - `"default-2024-11-15"` - - `"incomplete"` + - `score_threshold: optional number` - - `ShellCallOutput object { call_id, output, type, 5 more }` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - The streamed output items emitted by a shell tool call. + - `Computer object { type }` - - `call_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 unique ID of the shell tool call generated by the model. + - `type: "computer"` - - `output: array of BetaResponseFunctionShellCallOutputContent` + The type of the computer tool. Always `computer`. - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `"computer"` - - `outcome: object { type } or object { exit_code, type }` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - The exit or timeout outcome associated with this shell call. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `Timeout object { type }` + - `display_height: number` - Indicates that the shell call exceeded its configured time limit. + The height of the computer display. - - `type: "timeout"` + - `display_width: number` - The outcome type. Always `timeout`. + The width of the computer display. - - `"timeout"` + - `environment: "windows" or "mac" or "linux" or 2 more` - - `Exit object { exit_code, type }` + The type of computer environment to control. - Indicates that the shell commands finished and returned an exit code. + - `"windows"` - - `exit_code: number` + - `"mac"` - The exit code returned by the shell process. + - `"linux"` - - `type: "exit"` + - `"ubuntu"` - The outcome type. Always `exit`. + - `"browser"` - - `"exit"` + - `type: "computer_use_preview"` - - `stderr: string` + The type of the computer use tool. Always `computer_use_preview`. - Captured stderr output for the shell call. + - `"computer_use_preview"` - - `stdout: string` + - `WebSearch object { type, filters, search_context_size, user_location }` - Captured stdout output for the shell call. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `type: "shell_call_output"` + - `type: "web_search" or "web_search_2025_08_26"` - The type of the item. Always `shell_call_output`. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `"shell_call_output"` + - `"web_search"` - - `id: optional string` + - `"web_search_2025_08_26"` - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `filters: optional object { allowed_domains }` - - `agent: optional object { agent_name }` + Filters for the search. - The agent that produced this item. + - `allowed_domains: optional array of string` - - `agent_name: string` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - The canonical name of the agent that produced this item. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `caller: optional object { type } or object { caller_id, type }` + - `search_context_size: optional "low" or "medium" or "high"` - The execution context 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. - - `Direct object { type }` + - `"low"` - - `type: "direct"` + - `"medium"` - The caller type. Always `direct`. + - `"high"` - - `"direct"` + - `user_location: optional object { city, country, region, 2 more }` - - `Program object { caller_id, type }` + The approximate location of the user. - - `caller_id: string` + - `city: optional string` - The call ID of the program item that produced this tool call. + Free text input for the city of the user, e.g. `San Francisco`. - - `type: "program"` + - `country: optional string` - The caller type. Always `program`. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"program"` + - `region: optional string` - - `max_output_length: optional number` + Free text input for the region of the user, e.g. `California`. - The maximum number of UTF-8 characters captured for this shell call's combined output. + - `timezone: optional string` - - `status: optional "in_progress" or "completed" or "incomplete"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The status of the shell call output. + - `type: optional "approximate"` - - `"in_progress"` + The type of location approximation. Always `approximate`. - - `"completed"` + - `"approximate"` - - `"incomplete"` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `ApplyPatchCall object { call_id, operation, status, 4 more }` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - A tool call representing a request to create, delete, or update files using diff patches. + - `server_label: string` - - `call_id: string` + A label for this MCP server, used to identify it in tool calls. - The unique ID of the apply patch tool call generated by the model. + - `type: "mcp"` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + The type of the MCP tool. Always `mcp`. - The specific create, delete, or update instruction for the apply_patch tool call. + - `"mcp"` - - `CreateFile object { diff, path, type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - Instruction for creating a new file via the apply_patch tool. + The tool invocation context(s). - - `diff: string` + - `"direct"` - Unified diff content to apply when creating the file. + - `"programmatic"` - - `path: string` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - Path of the file to create relative to the workspace root. + List of allowed tool names or a filter object. - - `type: "create_file"` + - `McpAllowedTools = array of string` - The operation type. Always `create_file`. + A string array of allowed tool names - - `"create_file"` + - `McpToolFilter object { read_only, tool_names }` - - `DeleteFile object { path, type }` + A filter object to specify which tools are allowed. - Instruction for deleting an existing file via the apply_patch tool. + - `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 delete relative to the workspace root. + - `tool_names: optional array of string` - - `type: "delete_file"` + List of allowed tool names. - The operation type. Always `delete_file`. + - `authorization: optional string` - - `"delete_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. - - `UpdateFile object { diff, path, type }` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - Instruction for updating an existing file via the apply_patch tool. + 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). - - `diff: string` + Currently supported `connector_id` values are: - Unified diff content to apply to the existing 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` - - `path: string` + - `"connector_dropbox"` - Path of the file to update relative to the workspace root. + - `"connector_gmail"` - - `type: "update_file"` + - `"connector_googlecalendar"` - The operation type. Always `update_file`. + - `"connector_googledrive"` - - `"update_file"` + - `"connector_microsoftteams"` - - `status: "in_progress" or "completed"` + - `"connector_outlookcalendar"` - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `"connector_outlookemail"` - - `"in_progress"` + - `"connector_sharepoint"` - - `"completed"` + - `defer_loading: optional boolean` - - `type: "apply_patch_call"` + Whether this MCP tool is deferred and discovered via tool search. - The type of the item. Always `apply_patch_call`. + - `headers: optional map[string]` - - `"apply_patch_call"` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `id: optional string` + - `require_approval: optional object { always, never } or "always" or "never"` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + Specify which of the MCP server's tools require approval. - - `agent: optional object { agent_name }` + - `McpToolApprovalFilter object { always, never }` - The agent that produced this item. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `agent_name: string` + - `always: optional object { read_only, tool_names }` - The canonical name of the agent that produced this item. + 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`. + - `never: optional object { read_only, tool_names }` - - `"direct"` + A filter object to specify which tools are allowed. - - `Program object { caller_id, type }` + - `read_only: optional boolean` - - `caller_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 call ID of the program item that produced this tool call. + - `tool_names: optional array of string` - - `type: "program"` + List of allowed tool names. - The caller type. Always `program`. + - `McpToolApprovalSetting = "always" or "never"` - - `"program"` + 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. - - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` + - `"always"` - The streamed output emitted by an apply patch tool call. + - `"never"` - - `call_id: string` + - `server_description: optional string` - The unique ID of the apply patch tool call generated by the model. + Optional description of the MCP server, used to provide more context. - - `status: "completed" or "failed"` + - `server_url: optional string` - The status of the apply patch tool call output. One of `completed` or `failed`. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `"completed"` + - `tunnel_id: optional string` - - `"failed"` + 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: "apply_patch_call_output"` + - `CodeInterpreter object { container, type, allowed_callers }` - The type of the item. Always `apply_patch_call_output`. + A tool that runs Python code to help generate a response to a prompt. - - `"apply_patch_call_output"` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `id: optional string` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `string` - - `agent: optional object { agent_name }` + The container ID. - The agent that produced this item. + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `agent_name: string` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The canonical name of the agent that produced this item. + - `type: "auto"` - - `caller: optional object { type } or object { caller_id, type }` + Always `auto`. - The execution context that produced this tool call. + - `"auto"` - - `Direct object { type }` + - `file_ids: optional array of string` - - `type: "direct"` + An optional list of uploaded files to make available to your code. - The caller type. Always `direct`. + - `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 BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `BetaContainerNetworkPolicyDisabled object { type }` + + - `BetaContainerNetworkPolicyAllowlist 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"` - - `Program object { caller_id, type }` + - `"programmatic"` - - `caller_id: string` + - `ProgrammaticToolCalling object { type }` - The call ID of the program item that produced this tool call. + - `type: "programmatic_tool_calling"` - - `type: "program"` + The type of the tool. Always `programmatic_tool_calling`. - The caller type. Always `program`. + - `"programmatic_tool_calling"` - - `"program"` + - `ImageGeneration object { type, action, background, 9 more }` - - `output: optional string` + A tool that generates images using the GPT image models. - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `type: "image_generation"` - - `McpListTools object { id, server_label, tools, 3 more }` + The type of the image generation tool. Always `image_generation`. - A list of tools available on an MCP server. + - `"image_generation"` - - `id: string` + - `action: optional "generate" or "edit" or "auto"` - The unique ID of the list. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `server_label: string` + - `"generate"` - The label of the MCP server. + - `"edit"` - - `tools: array of object { input_schema, name, annotations, description }` + - `"auto"` - The tools available on the server. + - `background: optional "transparent" or "opaque" or "auto"` - - `input_schema: unknown` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - The JSON schema describing the tool's input. + - `"transparent"` - - `name: string` + - `"opaque"` - The name of the tool. + - `"auto"` - - `annotations: optional unknown` + - `input_fidelity: optional "high" or "low"` - Additional annotations about the tool. + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `description: optional string` + - `"high"` - The description of the tool. + - `"low"` - - `type: "mcp_list_tools"` + - `input_image_mask: optional object { file_id, image_url }` - The type of the item. Always `mcp_list_tools`. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `"mcp_list_tools"` + - `file_id: optional string` - - `agent: optional object { agent_name }` + File ID for the mask image. - The agent that produced this item. + - `image_url: optional string` - - `agent_name: string` + Base64-encoded mask image. - The canonical name of the agent that produced this item. + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `error: optional string` + The image generation model to use. Default: `gpt-image-1`. - Error message if the server could not list tools. + - `string` - - `McpApprovalRequest object { id, arguments, name, 3 more }` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - A request for human approval of a tool invocation. + The image generation model to use. Default: `gpt-image-1`. - - `id: string` + - `"gpt-image-1"` - The unique ID of the approval request. + - `"gpt-image-1-mini"` - - `arguments: string` + - `"gpt-image-1.5"` - A JSON string of arguments for the tool. + - `moderation: optional "auto" or "low"` - - `name: string` + Moderation level for the generated image. Default: `auto`. - The name of the tool to run. + - `"auto"` - - `server_label: string` + - `"low"` - The label of the MCP server making the request. + - `output_compression: optional number` - - `type: "mcp_approval_request"` + Compression level for the output image. Default: 100. - The type of the item. Always `mcp_approval_request`. + - `output_format: optional "png" or "webp" or "jpeg"` - - `"mcp_approval_request"` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `agent: optional object { agent_name }` + - `"png"` - The agent that produced this item. + - `"webp"` - - `agent_name: string` + - `"jpeg"` - The canonical name of the agent that produced this item. + - `partial_images: optional number` - - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - A response to an MCP approval request. + - `quality: optional "low" or "medium" or "high" or "auto"` - - `approval_request_id: string` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - The ID of the approval request being answered. + - `"low"` - - `approve: boolean` + - `"medium"` - Whether the request was approved. + - `"high"` - - `type: "mcp_approval_response"` + - `"auto"` - The type of the item. Always `mcp_approval_response`. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `"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`. - - `id: optional string` + - `string` - The unique ID of the approval response + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `agent: optional object { agent_name }` + 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 agent that produced this item. + - `"1024x1024"` - - `agent_name: string` + - `"1024x1536"` - The canonical name of the agent that produced this item. + - `"1536x1024"` - - `reason: optional string` + - `"auto"` - Optional reason for the decision. + - `LocalShell object { type }` - - `McpCall object { id, arguments, name, 7 more }` + A tool that allows the model to execute shell commands in a local environment. - An invocation of a tool on an MCP server. + - `type: "local_shell"` - - `id: string` + The type of the local shell tool. Always `local_shell`. - The unique ID of the tool call. + - `"local_shell"` - - `arguments: string` + - `Shell object { type, allowed_callers, environment }` - A JSON string of the arguments passed to the tool. + A tool that allows the model to execute shell commands. - - `name: string` + - `type: "shell"` - The name of the tool that was run. + The type of the shell tool. Always `shell`. - - `server_label: string` + - `"shell"` - The label of the MCP server running the tool. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "mcp_call"` + The tool invocation context(s). - The type of the item. Always `mcp_call`. + - `"direct"` - - `"mcp_call"` + - `"programmatic"` - - `agent: optional object { agent_name }` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - The agent that produced this item. + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `agent_name: string` + - `BetaLocalEnvironment object { type, skills }` - The canonical name of the agent that produced this item. + - `BetaContainerReference object { container_id, type }` - - `approval_request_id: optional string` + - `Custom object { name, type, allowed_callers, 3 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. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `error: optional string` + - `name: string` - The error from the tool call, if any. + The name of the custom tool, used to identify it in tool calls. - - `output: optional string` + - `type: "custom"` - The output from the tool call. + The type of the custom tool. Always `custom`. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `"custom"` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"in_progress"` + The tool invocation context(s). - - `"completed"` + - `"direct"` - - `"incomplete"` + - `"programmatic"` - - `"calling"` + - `defer_loading: optional boolean` - - `"failed"` + Whether this tool should be deferred and discovered via tool search. - - `CustomToolCallOutput object { call_id, output, type, 3 more }` + - `description: optional string` - The output of a custom tool call from your code, being sent back to the model. + Optional description of the custom tool, used to provide more context. - - `call_id: string` + - `format: optional object { type } or object { definition, syntax, type }` - The call ID, used to map this custom tool call output to a custom tool call. + The input format for the custom tool. Default is unconstrained text. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `Text object { type }` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + Unconstrained free-form text. - - `StringOutput = string` + - `type: "text"` - A string of the output of the custom tool call. + Unconstrained text format. Always `text`. - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `"text"` - Text, image, or file output of the custom tool call. + - `Grammar object { definition, syntax, type }` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + A grammar defined by the user. - A text input to the model. + - `definition: string` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + The grammar definition. - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `syntax: "lark" or "regex"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + The syntax of the grammar definition. One of `lark` or `regex`. - A file input to the model. + - `"lark"` - - `type: "custom_tool_call_output"` + - `"regex"` - The type of the custom tool call output. Always `custom_tool_call_output`. + - `type: "grammar"` - - `"custom_tool_call_output"` + Grammar format. Always `grammar`. - - `id: optional string` + - `"grammar"` - The unique ID of the custom tool call output in the OpenAI platform. + - `Namespace object { description, name, tools, type }` - - `agent: optional object { agent_name }` + Groups function/custom tools under a shared namespace. - The agent that produced this item. + - `description: string` - - `agent_name: string` + A description of the namespace shown to the model. - The canonical name of the agent that produced this item. + - `name: string` - - `caller: optional object { type } or object { caller_id, type }` + The namespace name used in tool calls (for example, `crm`). - The execution context that produced this tool call. + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `Direct object { type }` + The function/custom tools available inside this namespace. - - `type: "direct"` + - `Function object { name, type, allowed_callers, 5 more }` - The caller type. Always `direct`. + - `name: string` - - `"direct"` + - `type: "function"` - - `Program object { caller_id, type }` + - `"function"` - - `caller_id: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The call ID of the program item that produced this tool call. + The tool invocation context(s). - - `type: "program"` + - `"direct"` - The caller type. Always `program`. + - `"programmatic"` - - `"program"` + - `defer_loading: optional boolean` - - `CustomToolCall object { call_id, input, name, 5 more }` + Whether this function should be deferred and discovered via tool search. - A call to a custom tool created by the model. + - `description: optional string` - - `call_id: string` + - `output_schema: optional map[unknown]` - An identifier used to map this custom tool call to a tool call output. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `input: string` + - `parameters: optional unknown` - The input for the custom tool call generated by the model. + - `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 being called. + The name of the custom tool, used to identify it in tool calls. - - `type: "custom_tool_call"` + - `type: "custom"` - The type of the custom tool call. Always `custom_tool_call`. + The type of the custom tool. Always `custom`. - - `"custom_tool_call"` + - `"custom"` - - `id: optional string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The unique ID of the custom tool call in the OpenAI platform. + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` - - `agent: optional object { agent_name }` + - `defer_loading: optional boolean` - The agent that produced this item. + Whether this tool should be deferred and discovered via tool search. - - `agent_name: string` + - `description: optional string` - The canonical name of the agent that produced this item. + Optional description of the custom tool, used to provide more context. - - `caller: optional object { type } or object { caller_id, type }` + - `format: optional object { type } or object { definition, syntax, type }` - The execution context that produced this tool call. + The input format for the custom tool. Default is unconstrained text. - - `Direct object { type }` + - `Text object { type }` - - `type: "direct"` + Unconstrained free-form text. - - `"direct"` + - `type: "text"` - - `Program object { caller_id, type }` + Unconstrained text format. Always `text`. - - `caller_id: string` + - `"text"` - The call ID of the program item that produced this tool call. + - `Grammar object { definition, syntax, type }` - - `type: "program"` + A grammar defined by the user. - - `"program"` + - `definition: string` - - `namespace: optional string` + The grammar definition. - The namespace of the custom tool being called. + - `syntax: "lark" or "regex"` - - `CompactionTrigger object { type, agent }` + The syntax of the grammar definition. One of `lark` or `regex`. - Compacts the current context. Must be the final input item. + - `"lark"` - - `type: "compaction_trigger"` + - `"regex"` - The type of the item. Always `compaction_trigger`. + - `type: "grammar"` - - `"compaction_trigger"` + Grammar format. Always `grammar`. - - `agent: optional object { agent_name }` + - `"grammar"` - The agent that produced this item. + - `type: "namespace"` - - `agent_name: string` + The type of the tool. Always `namespace`. - The canonical name of the agent that produced this item. + - `"namespace"` - - `ItemReference object { id, agent, type }` + - `ToolSearch object { type, description, execution, parameters }` - An internal identifier for an item to reference. + Hosted or BYOT tool search configuration for deferred tools. - - `id: string` + - `type: "tool_search"` - The ID of the item to reference. + The type of the tool. Always `tool_search`. - - `agent: optional object { agent_name }` + - `"tool_search"` - The agent that produced this item. + - `description: optional string` - - `agent_name: string` + Description shown to the model for a client-executed tool search tool. - The canonical name of the agent that produced this item. + - `execution: optional "server" or "client"` - - `type: optional "item_reference"` + Whether tool search is executed by the server or by the client. - The type of item to reference. Always `item_reference`. + - `"server"` - - `"item_reference"` + - `"client"` - - `Program object { id, call_id, code, 3 more }` + - `parameters: optional unknown` - - `id: string` + Parameter schema for a client-executed tool search tool. - The unique ID of this program item. + - `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 stable call ID of the program item. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `code: string` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The JavaScript source executed by programmatic tool calling. + - `"web_search_preview"` - - `fingerprint: string` + - `"web_search_preview_2025_03_11"` - Opaque program replay fingerprint that must be round-tripped. + - `search_content_types: optional array of "text" or "image"` - - `type: "program"` + - `"text"` - The item type. Always `program`. + - `"image"` - - `"program"` + - `search_context_size: optional "low" or "medium" or "high"` - - `agent: optional object { agent_name }` + 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 agent that produced this item. + - `"low"` - - `agent_name: string` + - `"medium"` - The canonical name of the agent that produced this item. + - `"high"` - - `ProgramOutput object { id, call_id, result, 3 more }` + - `user_location: optional object { type, city, country, 2 more }` - - `id: string` + The user's location. - The unique ID of this program output item. + - `type: "approximate"` - - `call_id: string` + The type of location approximation. Always `approximate`. - The call ID of the program item. + - `"approximate"` - - `result: string` + - `city: optional string` - The result produced by the program item. + Free text input for the city of the user, e.g. `San Francisco`. - - `status: "completed" or "incomplete"` + - `country: optional string` - The terminal status of the program output. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"completed"` + - `region: optional string` - - `"incomplete"` + Free text input for the region of the user, e.g. `California`. - - `type: "program_output"` + - `timezone: optional string` - The item type. Always `program_output`. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"program_output"` + - `ApplyPatch object { type, allowed_callers }` - - `agent: optional object { agent_name }` + Allows the assistant to create, delete, or update files using unified diffs. - The agent that produced this item. + - `type: "apply_patch"` - - `agent_name: string` + The type of the tool. Always `apply_patch`. - The canonical name of the agent that produced this item. + - `"apply_patch"` - - `metadata: map[string]` + - `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: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + - `"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: "tool_search_output"` - - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` + The type of the item. Always `tool_search_output`. - 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. + - `"tool_search_output"` - - `"gpt-5.6-sol"` + - `agent: optional object { agent_name }` - - `"gpt-5.6-terra"` + The agent that produced this item. - - `"gpt-5.6-luna"` + - `agent_name: string` - - `"gpt-5.4"` + The canonical name of the agent that produced this item. - - `"gpt-5.4-mini"` + - `created_by: optional string` - - `"gpt-5.4-nano"` + The identifier of the actor that created the item. - - `"gpt-5.4-mini-2026-03-17"` + - `AdditionalTools object { id, role, tools, 2 more }` - - `"gpt-5.4-nano-2026-03-17"` + - `id: string` - - `"gpt-5.3-chat-latest"` + The unique ID of the additional tools item. - - `"gpt-5.2"` + - `role: "unknown" or "user" or "assistant" or 5 more` - - `"gpt-5.2-2025-12-11"` + The role that provided the additional tools. - - `"gpt-5.2-chat-latest"` + - `"unknown"` - - `"gpt-5.2-pro"` + - `"user"` - - `"gpt-5.2-pro-2025-12-11"` + - `"assistant"` - - `"gpt-5.1"` + - `"system"` - - `"gpt-5.1-2025-11-13"` + - `"critic"` - - `"gpt-5.1-codex"` + - `"discriminator"` - - `"gpt-5.1-mini"` + - `"developer"` - - `"gpt-5.1-chat-latest"` + - `"tool"` - - `"gpt-5"` + - `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-5-mini"` + The additional tool definitions made available at this item. - - `"gpt-5-nano"` + - `Function object { name, parameters, strict, 5 more }` - - `"gpt-5-2025-08-07"` + 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). - - `"gpt-5-mini-2025-08-07"` + - `name: string` - - `"gpt-5-nano-2025-08-07"` + The name of the function to call. - - `"gpt-5-chat-latest"` + - `parameters: map[unknown]` - - `"gpt-4.1"` + A JSON schema object describing the parameters of the function. - - `"gpt-4.1-mini"` + - `strict: boolean` - - `"gpt-4.1-nano"` + Whether strict parameter validation is enforced for this function tool. - - `"gpt-4.1-2025-04-14"` + - `type: "function"` - - `"gpt-4.1-mini-2025-04-14"` + The type of the function tool. Always `function`. - - `"gpt-4.1-nano-2025-04-14"` + - `"function"` - - `"o4-mini"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"o4-mini-2025-04-16"` + The tool invocation context(s). - - `"o3"` + - `"direct"` - - `"o3-2025-04-16"` + - `"programmatic"` - - `"o3-mini"` + - `defer_loading: optional boolean` - - `"o3-mini-2025-01-31"` + Whether this function is deferred and loaded via tool search. - - `"o1"` + - `description: optional string` - - `"o1-2024-12-17"` + A description of the function. Used by the model to determine whether or not to call the function. - - `"o1-preview"` + - `output_schema: optional map[unknown]` - - `"o1-preview-2024-09-12"` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `"o1-mini"` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `"o1-mini-2024-09-12"` + 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). - - `"gpt-4o"` + - `type: "file_search"` - - `"gpt-4o-2024-11-20"` + The type of the file search tool. Always `file_search`. - - `"gpt-4o-2024-08-06"` + - `"file_search"` - - `"gpt-4o-2024-05-13"` + - `vector_store_ids: array of string` - - `"gpt-4o-audio-preview"` + The IDs of the vector stores to search. - - `"gpt-4o-audio-preview-2024-10-01"` + - `filters: optional object { key, type, value } or object { filters, type }` - - `"gpt-4o-audio-preview-2024-12-17"` + A filter to apply. - - `"gpt-4o-audio-preview-2025-06-03"` + - `ComparisonFilter object { key, type, value }` - - `"gpt-4o-mini-audio-preview"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"gpt-4o-mini-audio-preview-2024-12-17"` + - `key: string` - - `"gpt-4o-search-preview"` + The key to compare against the value. - - `"gpt-4o-mini-search-preview"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `"gpt-4o-search-preview-2025-03-11"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"gpt-4o-mini-search-preview-2025-03-11"` + - `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 - - `"chatgpt-4o-latest"` + - `"eq"` - - `"codex-mini-latest"` + - `"ne"` - - `"gpt-4o-mini"` + - `"gt"` - - `"gpt-4o-mini-2024-07-18"` + - `"gte"` - - `"gpt-4-turbo"` + - `"lt"` - - `"gpt-4-turbo-2024-04-09"` + - `"lte"` - - `"gpt-4-0125-preview"` + - `"in"` - - `"gpt-4-turbo-preview"` + - `"nin"` - - `"gpt-4-1106-preview"` + - `value: string or number or boolean or array of string or number` - - `"gpt-4-vision-preview"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `"gpt-4"` + - `string` - - `"gpt-4-0314"` + - `number` - - `"gpt-4-0613"` + - `boolean` - - `"gpt-4-32k"` + - `array of string or number` - - `"gpt-4-32k-0314"` + - `string` - - `"gpt-4-32k-0613"` + - `number` - - `"gpt-3.5-turbo"` + - `CompoundFilter object { filters, type }` - - `"gpt-3.5-turbo-16k"` + Combine multiple filters using `and` or `or`. - - `"gpt-3.5-turbo-0301"` + - `filters: array of object { key, type, value } or unknown` - - `"gpt-3.5-turbo-0613"` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `"gpt-3.5-turbo-1106"` + - `ComparisonFilter object { key, type, value }` - - `"gpt-3.5-turbo-0125"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"gpt-3.5-turbo-16k-0613"` + - `key: string` - - `"o1-pro"` + The key to compare against the value. - - `"o1-pro-2025-03-19"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `"o3-pro"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"o3-pro-2025-06-10"` + - `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 - - `"o3-deep-research"` + - `"eq"` - - `"o3-deep-research-2025-06-26"` + - `"ne"` - - `"o4-mini-deep-research"` + - `"gt"` - - `"o4-mini-deep-research-2025-06-26"` + - `"gte"` - - `"computer-use-preview"` + - `"lt"` - - `"computer-use-preview-2025-03-11"` + - `"lte"` - - `"gpt-5-codex"` + - `"in"` - - `"gpt-5-pro"` + - `"nin"` - - `"gpt-5-pro-2025-10-06"` + - `value: string or number or boolean or array of string or number` - - `"gpt-5.1-codex-max"` + The value to compare against the attribute key; supports string, number, or boolean types. - `string` - - `object: "response"` + - `number` - The object type of this resource - always set to `response`. + - `boolean` - - `"response"` + - `array of string or number` - - `output: array of BetaResponseOutputItem` + - `string` - An array of content items generated by the model. + - `number` - - 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. + - `unknown` - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + - `type: "and" or "or"` - An output message from the model. + Type of operation: `and` or `or`. - - `FileSearchCall object { id, queries, status, 3 more }` + - `"and"` - The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + - `"or"` - - `id: string` + - `max_num_results: optional number` - The unique ID of the file search tool call. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `queries: array of string` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - The queries used to search for files. + Ranking options for search. - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `hybrid_search: optional object { embedding_weight, text_weight }` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `"in_progress"` + - `embedding_weight: number` - - `"searching"` + The weight of the embedding in the reciprocal ranking fusion. - - `"completed"` + - `text_weight: number` - - `"incomplete"` + The weight of the text in the reciprocal ranking fusion. - - `"failed"` + - `ranker: optional "auto" or "default-2024-11-15"` - - `type: "file_search_call"` + The ranker to use for the file search. - The type of the file search tool call. Always `file_search_call`. + - `"auto"` - - `"file_search_call"` + - `"default-2024-11-15"` - - `agent: optional object { agent_name }` + - `score_threshold: optional number` - The agent that produced this item. + 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. - - `agent_name: string` + - `Computer object { type }` - The canonical name of the agent that produced this item. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `type: "computer"` - The results of the file search tool call. + The type of the computer tool. Always `computer`. - - `attributes: optional map[string or number or boolean]` + - `"computer"` - 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. + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `string` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `number` + - `display_height: number` - - `boolean` + The height of the computer display. - - `file_id: optional string` + - `display_width: number` - The unique ID of the file. + The width of the computer display. - - `filename: optional string` + - `environment: "windows" or "mac" or "linux" or 2 more` - The name of the file. + The type of computer environment to control. - - `score: optional number` + - `"windows"` - The relevance score of the file - a value between 0 and 1. + - `"mac"` - - `text: optional string` + - `"linux"` - The text that was retrieved from the file. + - `"ubuntu"` - - `FunctionCall object { arguments, call_id, name, 6 more }` + - `"browser"` - A tool call to run a function. See the - [function calling guide](/docs/guides/function-calling) for more information. + - `type: "computer_use_preview"` - - `arguments: string` + The type of the computer use tool. Always `computer_use_preview`. - A JSON string of the arguments to pass to the function. + - `"computer_use_preview"` - - `call_id: string` + - `WebSearch object { type, filters, search_context_size, user_location }` - The unique ID of the function tool call generated by the model. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `name: string` + - `type: "web_search" or "web_search_2025_08_26"` - The name of the function to run. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `type: "function_call"` + - `"web_search"` - The type of the function tool call. Always `function_call`. + - `"web_search_2025_08_26"` - - `"function_call"` + - `filters: optional object { allowed_domains }` - - `id: optional string` + Filters for the search. - The unique ID of the function tool call. + - `allowed_domains: optional array of string` - - `agent: optional object { agent_name }` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - The agent that produced this item. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `agent_name: string` + - `search_context_size: optional "low" or "medium" or "high"` - The canonical name of the agent that produced this 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. - - `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"` + - `user_location: optional object { city, country, region, 2 more }` - - `"direct"` + The approximate location of the user. - - `Program object { caller_id, type }` + - `city: optional string` - - `caller_id: string` + Free text input for the city of the user, e.g. `San Francisco`. - The call ID of the program item that produced this tool call. + - `country: optional string` - - `type: "program"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"program"` + - `region: optional string` - - `namespace: optional string` + Free text input for the region of the user, e.g. `California`. - The namespace of the function to run. + - `timezone: optional string` - - `status: optional "in_progress" or "completed" or "incomplete"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `type: optional "approximate"` - - `"in_progress"` + The type of location approximation. Always `approximate`. - - `"completed"` + - `"approximate"` - - `"incomplete"` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `FunctionCallOutput object { id, call_id, output, 5 more }` + 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 function call tool output. + A label for this MCP server, used to identify it in tool calls. - - `call_id: string` + - `type: "mcp"` - The unique ID of the function tool call generated by the model. + The type of the MCP tool. Always `mcp`. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `"mcp"` - The output from the function 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 function call. + - `"direct"` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `"programmatic"` - Text, image, or file output of the function call. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `BetaResponseInputText 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` - - `BetaResponseInputImage 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 }` - - `BetaResponseInputFile 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` - - `status: "in_progress" or "completed" or "incomplete"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `tool_names: optional array of string` - - `"in_progress"` + List of allowed tool names. - - `"completed"` + - `authorization: optional string` - - `"incomplete"` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - - `type: "function_call_output"` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - The type of the function tool call output. Always `function_call_output`. + 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). - - `"function_call_output"` + Currently supported `connector_id` values are: - - `agent: optional object { agent_name }` + - 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 agent that produced this item. + - `"connector_dropbox"` - - `agent_name: string` + - `"connector_gmail"` - The canonical name of the agent that produced this item. + - `"connector_googlecalendar"` - - `caller: optional object { type } or object { caller_id, type }` + - `"connector_googledrive"` - The execution context that produced this tool call. + - `"connector_microsoftteams"` - - `Direct object { type }` + - `"connector_outlookcalendar"` - - `type: "direct"` + - `"connector_outlookemail"` - The caller type. Always `direct`. + - `"connector_sharepoint"` - - `"direct"` + - `defer_loading: optional boolean` - - `Program object { caller_id, type }` + Whether this MCP tool is deferred and discovered via tool search. - - `caller_id: string` + - `headers: optional map[string]` - The call ID of the program item that produced this tool call. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `type: "program"` + - `require_approval: optional object { always, never } or "always" or "never"` - The caller type. Always `program`. + Specify which of the MCP server's tools require approval. - - `"program"` + - `McpToolApprovalFilter object { always, never }` - - `created_by: 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 identifier of the actor that created the item. + - `always: optional object { read_only, tool_names }` - - `AgentMessage object { id, author, content, 3 more }` + A filter object to specify which tools are allowed. - - `id: string` + - `read_only: optional boolean` - The unique ID of the agent message. + 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. - - `author: string` + - `tool_names: optional array of string` - The sending agent identity. + List of allowed tool names. - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + - `never: optional object { read_only, tool_names }` - Encrypted content sent between agents. + A filter object to specify which tools are allowed. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `read_only: optional boolean` - A text input to the model. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `BetaResponseOutputText object { annotations, logprobs, text, type }` + - `tool_names: optional array of string` - A text output from the model. + List of allowed tool names. - - `Text object { text, type }` + - `McpToolApprovalSetting = "always" or "never"` - A text content. + 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. - - `text: string` + - `"always"` - - `type: "text"` + - `"never"` - - `"text"` + - `server_description: optional string` - - `SummaryText object { text, type }` + Optional description of the MCP server, used to provide more context. - A summary text from the model. + - `server_url: optional string` - - `text: string` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - A summary of the reasoning output from the model so far. + - `tunnel_id: optional string` - - `type: "summary_text"` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - The type of the object. Always `summary_text`. + - `CodeInterpreter object { container, type, allowed_callers }` - - `"summary_text"` + A tool that runs Python code to help generate a response to a prompt. - - `ReasoningText object { text, type }` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - Reasoning text from the model. + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - - `text: string` + - `string` - The reasoning text from the model. + The container ID. - - `type: "reasoning_text"` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - The type of the reasoning text. Always `reasoning_text`. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `"reasoning_text"` + - `type: "auto"` - - `BetaResponseOutputRefusal object { refusal, type }` + Always `auto`. - A refusal from the model. + - `"auto"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `file_ids: optional array of string` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + An optional list of uploaded files to make available to your code. - - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - A screenshot of a computer. + The memory limit for the code interpreter container. - - `detail: "low" or "high" or "auto" or "original"` + - `"1g"` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"4g"` - - `"low"` + - `"16g"` - - `"high"` + - `"64g"` - - `"auto"` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `"original"` + Network access policy for the container. - - `file_id: string` + - `BetaContainerNetworkPolicyDisabled object { type }` - The identifier of an uploaded file that contains the screenshot. + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `image_url: string` + - `type: "code_interpreter"` - The URL of the screenshot image. + The type of the code interpreter tool. Always `code_interpreter`. - - `type: "computer_screenshot"` + - `"code_interpreter"` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"computer_screenshot"` + The tool invocation context(s). - - `prompt_cache_breakpoint: optional object { mode }` + - `"direct"` - 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. + - `"programmatic"` - - `mode: "explicit"` + - `ProgrammaticToolCalling object { type }` - The breakpoint mode. Always `explicit`. + - `type: "programmatic_tool_calling"` - - `"explicit"` + The type of the tool. Always `programmatic_tool_calling`. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `"programmatic_tool_calling"` - A file input to the model. + - `ImageGeneration object { type, action, background, 9 more }` - - `EncryptedContent object { encrypted_content, type }` + A tool that generates images using the GPT image models. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `type: "image_generation"` - - `encrypted_content: string` + The type of the image generation tool. Always `image_generation`. - Opaque encrypted content. + - `"image_generation"` - - `type: "encrypted_content"` + - `action: optional "generate" or "edit" or "auto"` - The type of the input item. Always `encrypted_content`. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `"encrypted_content"` + - `"generate"` - - `recipient: string` + - `"edit"` - The destination agent identity. + - `"auto"` - - `type: "agent_message"` + - `background: optional "transparent" or "opaque" or "auto"` - The type of the item. Always `agent_message`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `"agent_message"` + - `"transparent"` - - `agent: optional object { agent_name }` + - `"opaque"` - The agent that produced this item. + - `"auto"` - - `agent_name: string` + - `input_fidelity: optional "high" or "low"` - The canonical name of the agent that produced this item. + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `MultiAgentCall object { id, action, arguments, 3 more }` + - `"high"` - - `id: string` + - `"low"` - The unique ID of the multi-agent call item. + - `input_image_mask: optional object { file_id, image_url }` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - The multi-agent action to execute. + - `file_id: optional string` - - `"spawn_agent"` + File ID for the mask image. - - `"interrupt_agent"` + - `image_url: optional string` - - `"list_agents"` + Base64-encoded mask image. - - `"send_message"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `"followup_task"` + The image generation model to use. Default: `gpt-image-1`. - - `"wait_agent"` + - `string` - - `arguments: string` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The JSON string of arguments generated for the action. + The image generation model to use. Default: `gpt-image-1`. - - `call_id: string` + - `"gpt-image-1"` - The unique ID linking this call to its output. + - `"gpt-image-1-mini"` - - `type: "multi_agent_call"` + - `"gpt-image-1.5"` - The type of the multi-agent call. Always `multi_agent_call`. + - `moderation: optional "auto" or "low"` - - `"multi_agent_call"` + Moderation level for the generated image. Default: `auto`. - - `agent: optional object { agent_name }` + - `"auto"` - The agent that produced this item. + - `"low"` - - `agent_name: string` + - `output_compression: optional number` - The canonical name of the agent that produced this item. + Compression level for the output image. Default: 100. - - `MultiAgentCallOutput object { id, action, call_id, 3 more }` + - `output_format: optional "png" or "webp" or "jpeg"` - - `id: string` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The unique ID of the multi-agent call output item. + - `"png"` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `"webp"` - The multi-agent action that produced this result. + - `"jpeg"` - - `"spawn_agent"` + - `partial_images: optional number` - - `"interrupt_agent"` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `"list_agents"` + - `quality: optional "low" or "medium" or "high" or "auto"` - - `"send_message"` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `"followup_task"` + - `"low"` - - `"wait_agent"` + - `"medium"` - - `call_id: string` + - `"high"` - The unique ID of the multi-agent call. + - `"auto"` - - `output: array of BetaResponseOutputText` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - Text output returned by the multi-agent 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`. - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + - `string` - The annotations of the text output. + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + 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`. - - `text: string` + - `"1024x1024"` - The text output from the model. + - `"1024x1536"` - - `type: "output_text"` + - `"1536x1024"` - The type of the output text. Always `output_text`. + - `"auto"` - - `type: "multi_agent_call_output"` + - `LocalShell object { type }` - The type of the multi-agent result. Always `multi_agent_call_output`. + A tool that allows the model to execute shell commands in a local environment. - - `"multi_agent_call_output"` + - `type: "local_shell"` - - `agent: optional object { agent_name }` + The type of the local shell tool. Always `local_shell`. - The agent that produced this item. + - `"local_shell"` - - `agent_name: string` + - `Shell object { type, allowed_callers, environment }` - The canonical name of the agent that produced this item. + A tool that allows the model to execute shell commands. - - `WebSearchCall object { id, action, status, 2 more }` + - `type: "shell"` - The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + The type of the shell tool. Always `shell`. - - `id: string` + - `"shell"` - The unique ID of the web search tool call. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + The tool invocation context(s). - 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). + - `"direct"` - - `Search object { type, queries, query, sources }` + - `"programmatic"` - Action type "search" - Performs a web search query. + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `type: "search"` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - The action type. + - `BetaLocalEnvironment object { type, skills }` - - `"search"` + - `BetaContainerReference object { container_id, type }` - - `queries: optional array of string` + - `Custom object { name, type, allowed_callers, 3 more }` - The search queries. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `query: optional string` + - `name: string` - The search query. + The name of the custom tool, used to identify it in tool calls. - - `sources: optional array of object { type, url }` + - `type: "custom"` - The sources used in the search. + The type of the custom tool. Always `custom`. - - `type: "url"` + - `"custom"` - The type of source. Always `url`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"url"` + The tool invocation context(s). - - `url: string` + - `"direct"` - The URL of the source. + - `"programmatic"` - - `OpenPage object { type, url }` + - `defer_loading: optional boolean` - Action type "open_page" - Opens a specific URL from search results. + Whether this tool should be deferred and discovered via tool search. - - `type: "open_page"` + - `description: optional string` - The action type. + Optional description of the custom tool, used to provide more context. - - `"open_page"` + - `format: optional object { type } or object { definition, syntax, type }` - - `url: optional string` + The input format for the custom tool. Default is unconstrained text. - The URL opened by the model. + - `Text object { type }` - - `FindInPage object { pattern, type, url }` + Unconstrained free-form text. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `type: "text"` - - `pattern: string` + Unconstrained text format. Always `text`. - The pattern or text to search for within the page. + - `"text"` - - `type: "find_in_page"` + - `Grammar object { definition, syntax, type }` - The action type. + A grammar defined by the user. - - `"find_in_page"` + - `definition: string` - - `url: string` + The grammar definition. - The URL of the page searched for the pattern. + - `syntax: "lark" or "regex"` - - `status: "in_progress" or "searching" or "completed" or "failed"` + The syntax of the grammar definition. One of `lark` or `regex`. - The status of the web search tool call. + - `"lark"` - - `"in_progress"` + - `"regex"` - - `"searching"` + - `type: "grammar"` - - `"completed"` + Grammar format. Always `grammar`. - - `"failed"` + - `"grammar"` - - `type: "web_search_call"` + - `Namespace object { description, name, tools, type }` - The type of the web search tool call. Always `web_search_call`. + Groups function/custom tools under a shared namespace. - - `"web_search_call"` + - `description: string` - - `agent: optional object { agent_name }` + A description of the namespace shown to the model. - The agent that produced this item. + - `name: string` - - `agent_name: string` + The namespace name used in tool calls (for example, `crm`). - The canonical name of the agent that produced this item. + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + The function/custom tools available inside this namespace. - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + - `Function object { name, type, allowed_callers, 5 more }` - - `id: string` + - `name: string` - The unique ID of the computer call. + - `type: "function"` - - `call_id: string` + - `"function"` - An identifier used when responding to the tool call with output. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `pending_safety_checks: array of object { id, code, message }` + The tool invocation context(s). - The pending safety checks for the computer call. + - `"direct"` + + - `"programmatic"` - - `id: string` + - `defer_loading: optional boolean` - The ID of the pending safety check. + Whether this function should be deferred and discovered via tool search. - - `code: optional string` + - `description: optional string` - The type of the pending safety check. + - `output_schema: optional map[unknown]` - - `message: optional string` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - Details about the pending safety check. + - `parameters: optional unknown` - - `status: "in_progress" or "completed" or "incomplete"` + - `strict: optional boolean` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + 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 }` - - `"completed"` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `"incomplete"` + - `name: string` - - `type: "computer_call"` + The name of the custom tool, used to identify it in tool calls. - The type of the computer call. Always `computer_call`. + - `type: "custom"` - - `"computer_call"` + The type of the custom tool. Always `custom`. - - `action: optional BetaComputerAction` + - `"custom"` - A click action. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `actions: optional BetaComputerActionList` + The tool invocation context(s). - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `"direct"` - - `agent: optional object { agent_name }` + - `"programmatic"` - The agent that produced this item. + - `defer_loading: optional boolean` - - `agent_name: string` + Whether this tool should be deferred and discovered via tool search. - The canonical name of the agent that produced this item. + - `description: optional string` - - `ComputerCallOutput object { id, call_id, output, 5 more }` + Optional description of the custom tool, used to provide more context. - - `id: string` + - `format: optional object { type } or object { definition, syntax, type }` - The unique ID of the computer call tool output. + The input format for the custom tool. Default is unconstrained text. - - `call_id: string` + - `Text object { type }` - The ID of the computer tool call that produced the output. + Unconstrained free-form text. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `type: "text"` - A computer screenshot image used with the computer use tool. + Unconstrained text format. Always `text`. - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + - `"text"` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `Grammar object { definition, syntax, type }` - - `"completed"` + A grammar defined by the user. - - `"incomplete"` + - `definition: string` - - `"failed"` + The grammar definition. - - `"in_progress"` + - `syntax: "lark" or "regex"` - - `type: "computer_call_output"` + The syntax of the grammar definition. One of `lark` or `regex`. - The type of the computer tool call output. Always `computer_call_output`. + - `"lark"` - - `"computer_call_output"` + - `"regex"` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `type: "grammar"` - The safety checks reported by the API that have been acknowledged by the - developer. + Grammar format. Always `grammar`. - - `id: string` + - `"grammar"` - The ID of the pending safety check. + - `type: "namespace"` - - `code: optional string` + The type of the tool. Always `namespace`. - The type of the pending safety check. + - `"namespace"` - - `message: optional string` + - `ToolSearch object { type, description, execution, parameters }` - Details about the pending safety check. + Hosted or BYOT tool search configuration for deferred tools. - - `agent: optional object { agent_name }` + - `type: "tool_search"` - The agent that produced this item. + The type of the tool. Always `tool_search`. - - `agent_name: string` + - `"tool_search"` - The canonical name of the agent that produced this item. + - `description: optional string` - - `created_by: optional string` + Description shown to the model for a client-executed tool search tool. - The identifier of the actor that created the item. + - `execution: optional "server" or "client"` - - `Reasoning object { id, summary, type, 4 more }` + Whether tool search is executed by the server or by the client. - 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). + - `"server"` - - `id: string` + - `"client"` - The unique identifier of the reasoning content. + - `parameters: optional unknown` - - `summary: array of object { text, type }` + Parameter schema for a client-executed tool search tool. - Reasoning summary content. + - `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). - A summary of the reasoning output from the model so far. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `type: "summary_text"` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The type of the object. Always `summary_text`. + - `"web_search_preview"` - - `"summary_text"` + - `"web_search_preview_2025_03_11"` - - `type: "reasoning"` + - `search_content_types: optional array of "text" or "image"` - The type of the object. Always `reasoning`. + - `"text"` - - `"reasoning"` + - `"image"` - - `agent: optional object { agent_name }` + - `search_context_size: optional "low" or "medium" or "high"` - The agent that produced this 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. - - `agent_name: string` + - `"low"` - The canonical name of the agent that produced this item. + - `"medium"` - - `content: optional array of object { text, type }` + - `"high"` - Reasoning text content. + - `user_location: optional object { type, city, country, 2 more }` - - `text: string` + The user's location. - The reasoning text from the model. + - `type: "approximate"` - - `type: "reasoning_text"` + The type of location approximation. Always `approximate`. - The type of the reasoning text. Always `reasoning_text`. + - `"approximate"` - - `"reasoning_text"` + - `city: optional string` - - `encrypted_content: optional string` + Free text input for the city of the user, e.g. `San Francisco`. - 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. + - `country: optional string` - - `status: optional "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 item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `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`. - - `Program object { id, call_id, code, 3 more }` + - `ApplyPatch object { type, allowed_callers }` - - `id: string` + Allows the assistant to create, delete, or update files using unified diffs. - The unique ID of the program item. + - `type: "apply_patch"` - - `call_id: string` + The type of the tool. Always `apply_patch`. - The stable call ID of the program item. + - `"apply_patch"` - - `code: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The JavaScript source executed by programmatic tool calling. + The tool invocation context(s). - - `fingerprint: string` + - `"direct"` - Opaque program replay fingerprint that must be round-tripped. + - `"programmatic"` - - `type: "program"` + - `type: "additional_tools"` - The type of the item. Always `program`. + The type of the item. Always `additional_tools`. - - `"program"` + - `"additional_tools"` - `agent: optional object { agent_name }` @@ -164624,33 +163696,23 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `ProgramOutput object { id, call_id, result, 3 more }` - - - `id: string` - - The unique ID of the program output item. - - - `call_id: string` - - The call ID of the program item. - - - `result: string` + - `Compaction object { id, encrypted_content, type, 2 more }` - The result produced by the program item. + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - - `status: "completed" or "incomplete"` + - `id: string` - The terminal status of the program output item. + The unique ID of the compaction item. - - `"completed"` + - `encrypted_content: string` - - `"incomplete"` + The encrypted content that was produced by compaction. - - `type: "program_output"` + - `type: "compaction"` - The type of the item. Always `program_output`. + The type of the item. Always `compaction`. - - `"program_output"` + - `"compaction"` - `agent: optional object { agent_name }` @@ -164660,43 +163722,39 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `ToolSearchCall object { id, arguments, call_id, 5 more }` - - - `id: string` - - The unique ID of the tool search call item. - - - `arguments: unknown` + - `created_by: optional string` - Arguments used for the tool search call. + The identifier of the actor that created the item. - - `call_id: string` + - `ImageGenerationCall object { id, result, status, 2 more }` - The unique ID of the tool search call generated by the model. + An image generation request made by the model. - - `execution: "server" or "client"` + - `id: string` - Whether tool search was executed by the server or by the client. + The unique ID of the image generation call. - - `"server"` + - `result: string` - - `"client"` + The generated image encoded in base64. - - `status: "in_progress" or "completed" or "incomplete"` + - `status: "in_progress" or "completed" or "generating" or "failed"` - The status of the tool search call item that was recorded. + The status of the image generation call. - `"in_progress"` - `"completed"` - - `"incomplete"` + - `"generating"` - - `type: "tool_search_call"` + - `"failed"` - The type of the item. Always `tool_search_call`. + - `type: "image_generation_call"` - - `"tool_search_call"` + The type of the image generation call. Always `image_generation_call`. + + - `"image_generation_call"` - `agent: optional object { agent_name }` @@ -164706,1078 +163764,1090 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` - - The identifier of the actor that created the item. + - `CodeInterpreterCall object { id, code, container_id, 4 more }` - - `ToolSearchOutput object { id, call_id, execution, 5 more }` + A tool call to run code. - `id: string` - The unique ID of the tool search output item. + The unique ID of the code interpreter tool call. - - `call_id: string` + - `code: string` - The unique ID of the tool search call generated by the model. + The code to run, or null if not available. - - `execution: "server" or "client"` + - `container_id: string` - Whether tool search was executed by the server or by the client. + The ID of the container used to run the code. - - `"server"` + - `outputs: array of object { logs, type } or object { type, url }` - - `"client"` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `status: "in_progress" or "completed" or "incomplete"` + - `Logs object { logs, type }` - The status of the tool search output item that was recorded. + The logs output from the code interpreter. - - `"in_progress"` + - `logs: string` - - `"completed"` + The logs output from the code interpreter. - - `"incomplete"` + - `type: "logs"` - - `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 type of the output. Always `logs`. - The loaded tool definitions returned by tool search. + - `"logs"` - - `Function object { name, parameters, strict, 5 more }` + - `Image object { type, url }` - 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 image output from the code interpreter. - - `name: string` + - `type: "image"` - The name of the function to call. + The type of the output. Always `image`. - - `parameters: map[unknown]` + - `"image"` - A JSON schema object describing the parameters of the function. + - `url: string` - - `strict: boolean` + The URL of the image output from the code interpreter. - Whether strict parameter validation is enforced for this function tool. + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - `type: "function"` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - 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). + - `"interpreting"` - - `"direct"` + - `"failed"` - - `"programmatic"` + - `type: "code_interpreter_call"` - - `defer_loading: optional boolean` + The type of the code interpreter tool call. Always `code_interpreter_call`. - Whether this function is deferred and loaded via tool search. + - `"code_interpreter_call"` - - `description: optional string` + - `agent: optional object { agent_name }` - A description of the function. Used by the model to determine whether or not to call the function. + The agent that produced this item. - - `output_schema: optional map[unknown]` + - `agent_name: string` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The canonical name of the agent that produced this item. - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `LocalShellCall object { id, action, call_id, 3 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). + A tool call to run a command on the local shell. - - `type: "file_search"` + - `id: string` - The type of the file search tool. Always `file_search`. + The unique ID of the local shell call. - - `"file_search"` + - `action: object { command, env, type, 3 more }` - - `vector_store_ids: array of string` + Execute a shell command on the server. - The IDs of the vector stores to search. + - `command: array of string` - - `filters: optional object { key, type, value } or object { filters, type }` + The command to run. - A filter to apply. + - `env: map[string]` - - `ComparisonFilter object { key, type, value }` + Environment variables to set for the command. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `type: "exec"` - - `key: string` + The type of the local shell action. Always `exec`. - The key to compare against the value. + - `"exec"` - - `type: "eq" or "ne" or "gt" or 5 more` + - `timeout_ms: optional number` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + Optional timeout in milliseconds for the command. - - `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 + - `user: optional string` - - `"eq"` + Optional user to run the command as. - - `"ne"` + - `working_directory: optional string` - - `"gt"` + Optional working directory to run the command in. - - `"gte"` + - `call_id: string` - - `"lt"` + The unique ID of the local shell tool call generated by the model. - - `"lte"` + - `status: "in_progress" or "completed" or "incomplete"` - - `"in"` + The status of the local shell call. - - `"nin"` + - `"in_progress"` - - `value: string or number or boolean or array of string or number` + - `"completed"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `"incomplete"` - - `string` + - `type: "local_shell_call"` - - `number` + The type of the local shell call. Always `local_shell_call`. - - `boolean` + - `"local_shell_call"` - - `array of string or number` + - `agent: optional object { agent_name }` - - `string` + The agent that produced this item. - - `number` + - `agent_name: string` - - `CompoundFilter object { filters, type }` + The canonical name of the agent that produced this item. - Combine multiple filters using `and` or `or`. + - `LocalShellCallOutput object { id, output, type, 2 more }` - - `filters: array of object { key, type, value } or unknown` + The output of a local shell tool call. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `id: string` - - `ComparisonFilter object { key, type, value }` + The unique ID of the local shell tool call generated by the model. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `output: string` - - `key: string` + A JSON string of the output of the local shell tool call. - The key to compare against the value. + - `type: "local_shell_call_output"` - - `type: "eq" or "ne" or "gt" or 5 more` + The type of the local shell tool call output. Always `local_shell_call_output`. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"local_shell_call_output"` - - `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 + - `agent: optional object { agent_name }` - - `"eq"` + The agent that produced this item. - - `"ne"` + - `agent_name: string` - - `"gt"` + The canonical name of the agent that produced this item. - - `"gte"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"lt"` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `"lte"` + - `"in_progress"` - - `"in"` + - `"completed"` - - `"nin"` + - `"incomplete"` - - `value: string or number or boolean or array of string or number` + - `ShellCall object { id, action, call_id, 6 more }` - The value to compare against the attribute key; supports string, number, or boolean types. + A tool call that executes one or more shell commands in a managed environment. - - `string` + - `id: string` - - `number` + The unique ID of the shell tool call. Populated when this item is returned via API. - - `boolean` + - `action: object { commands, max_output_length, timeout_ms }` - - `array of string or number` + The shell commands and limits that describe how to run the tool call. - - `string` + - `commands: array of string` - - `number` + - `max_output_length: number` - - `unknown` + Optional maximum number of characters to return from each command. - - `type: "and" or "or"` + - `timeout_ms: number` - Type of operation: `and` or `or`. + Optional timeout in milliseconds for the commands. - - `"and"` + - `call_id: string` - - `"or"` + The unique ID of the shell tool call generated by the model. - - `max_num_results: optional number` + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + Represents the use of a local environment to perform shell actions. - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `BetaResponseLocalEnvironment object { type }` - Ranking options for search. + Represents the use of a local environment to perform shell actions. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `type: "local"` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + The environment type. Always `local`. - - `embedding_weight: number` + - `"local"` - The weight of the embedding in the reciprocal ranking fusion. + - `BetaResponseContainerReference object { container_id, type }` - - `text_weight: number` + Represents a container created with /v1/containers. - The weight of the text in the reciprocal ranking fusion. + - `container_id: string` - - `ranker: optional "auto" or "default-2024-11-15"` + - `type: "container_reference"` - The ranker to use for the file search. + The environment type. Always `container_reference`. - - `"auto"` + - `"container_reference"` - - `"default-2024-11-15"` + - `status: "in_progress" or "completed" or "incomplete"` - - `score_threshold: optional number` + The status of the shell call. One of `in_progress`, `completed`, or `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. + - `"in_progress"` - - `Computer object { type }` + - `"completed"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"incomplete"` - - `type: "computer"` + - `type: "shell_call"` - The type of the computer tool. Always `computer`. + The type of the item. Always `shell_call`. - - `"computer"` + - `"shell_call"` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `agent: optional object { agent_name }` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The agent that produced this item. - - `display_height: number` + - `agent_name: string` - The height of the computer display. + The canonical name of the agent that produced this item. - - `display_width: number` + - `caller: optional object { type } or object { caller_id, type }` - The width of the computer display. + The execution context that produced this tool call. - - `environment: "windows" or "mac" or "linux" or 2 more` + - `Direct object { type }` - The type of computer environment to control. + - `type: "direct"` - - `"windows"` + - `"direct"` - - `"mac"` + - `Program object { caller_id, type }` - - `"linux"` + - `caller_id: string` - - `"ubuntu"` + The call ID of the program item that produced this tool call. - - `"browser"` + - `type: "program"` - - `type: "computer_use_preview"` + - `"program"` - The type of the computer use tool. Always `computer_use_preview`. + - `created_by: optional string` - - `"computer_use_preview"` + The ID of the entity that created this tool call. - - `WebSearch object { type, filters, search_context_size, user_location }` + - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + The output of a shell tool call that was emitted. - - `type: "web_search" or "web_search_2025_08_26"` + - `id: string` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + The unique ID of the shell call output. Populated when this item is returned via API. - - `"web_search"` + - `call_id: string` - - `"web_search_2025_08_26"` + The unique ID of the shell tool call generated by the model. - - `filters: optional object { allowed_domains }` + - `max_output_length: number` - Filters for the search. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - - `allowed_domains: optional array of string` + - `output: array of object { outcome, stderr, stdout, created_by }` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + An array of shell call output contents - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `outcome: object { type } or object { exit_code, type }` - - `search_context_size: optional "low" or "medium" or "high"` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - 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 object { type }` - - `"low"` + Indicates that the shell call exceeded its configured time limit. - - `"medium"` + - `type: "timeout"` - - `"high"` + The outcome type. Always `timeout`. - - `user_location: optional object { city, country, region, 2 more }` + - `"timeout"` - The approximate location of the user. + - `Exit object { exit_code, type }` - - `city: optional string` + Indicates that the shell commands finished and returned an exit code. - Free text input for the city of the user, e.g. `San Francisco`. + - `exit_code: number` - - `country: optional string` + Exit code from the shell process. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `type: "exit"` - - `region: optional string` + The outcome type. Always `exit`. - Free text input for the region of the user, e.g. `California`. + - `"exit"` - - `timezone: optional string` + - `stderr: string` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The standard error output that was captured. - - `type: optional "approximate"` + - `stdout: string` - The type of location approximation. Always `approximate`. + The standard output that was captured. - - `"approximate"` + - `created_by: optional string` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + The identifier of the actor that created the item. - 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 "completed" or "incomplete"` - - `server_label: string` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - A label for this MCP server, used to identify it in tool calls. + - `"in_progress"` - - `type: "mcp"` + - `"completed"` - The type of the MCP tool. Always `mcp`. + - `"incomplete"` - - `"mcp"` + - `type: "shell_call_output"` - - `allowed_callers: optional array of "direct" or "programmatic"` + The type of the shell call output. Always `shell_call_output`. - The tool invocation context(s). + - `"shell_call_output"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` - `"direct"` - - `"programmatic"` + - `Program object { caller_id, type }` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `caller_id: string` - List of allowed tool names or a filter object. + The call ID of the program item that produced this tool call. - - `McpAllowedTools = array of string` + - `type: "program"` - A string array of allowed tool names + - `"program"` - - `McpToolFilter object { read_only, tool_names }` + - `created_by: optional string` - A filter object to specify which tools are allowed. + The identifier of the actor that created the item. - - `read_only: optional boolean` + - `ApplyPatchCall object { id, call_id, operation, 5 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 tool call that applies file diffs by creating, deleting, or updating files. - - `tool_names: optional array of string` + - `id: string` - List of allowed tool names. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `authorization: optional string` + - `call_id: string` - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + The unique ID of the apply patch tool call generated by the model. - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - 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). + One of the create_file, delete_file, or update_file operations applied via apply_patch. - Currently supported `connector_id` values are: + - `CreateFile object { diff, path, type }` - - 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` + Instruction describing how to create a file via the apply_patch tool. - - `"connector_dropbox"` + - `diff: string` - - `"connector_gmail"` + Diff to apply. - - `"connector_googlecalendar"` + - `path: string` - - `"connector_googledrive"` + Path of the file to create. - - `"connector_microsoftteams"` + - `type: "create_file"` - - `"connector_outlookcalendar"` + Create a new file with the provided diff. - - `"connector_outlookemail"` + - `"create_file"` - - `"connector_sharepoint"` + - `DeleteFile object { path, type }` - - `defer_loading: optional boolean` + Instruction describing how to delete a file via the apply_patch tool. - Whether this MCP tool is deferred and discovered via tool search. + - `path: string` - - `headers: optional map[string]` + Path of the file to delete. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `type: "delete_file"` - - `require_approval: optional object { always, never } or "always" or "never"` + Delete the specified file. - Specify which of the MCP server's tools require approval. + - `"delete_file"` - - `McpToolApprovalFilter object { always, never }` + - `UpdateFile 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 describing how to update a file via the apply_patch tool. - - `always: optional object { read_only, tool_names }` + - `diff: string` - A filter object to specify which tools are allowed. + Diff to apply. - - `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 update. - - `tool_names: optional array of string` + - `type: "update_file"` - List of allowed tool names. + Update an existing file with the provided diff. - - `never: optional object { read_only, tool_names }` + - `"update_file"` - A filter object to specify which tools are allowed. + - `status: "in_progress" or "completed"` - - `read_only: optional boolean` + The status of the apply patch tool call. One of `in_progress` or `completed`. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `"in_progress"` - - `tool_names: optional array of string` + - `"completed"` - List of allowed tool names. + - `type: "apply_patch_call"` - - `McpToolApprovalSetting = "always" or "never"` + The type of the item. Always `apply_patch_call`. - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `"apply_patch_call"` - - `"always"` + - `agent: optional object { agent_name }` - - `"never"` + The agent that produced this item. - - `server_description: optional string` + - `agent_name: string` - Optional description of the MCP server, used to provide more context. + The canonical name of the agent that produced this item. - - `server_url: optional string` + - `caller: optional object { type } or object { caller_id, type }` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + The execution context that produced this tool call. - - `tunnel_id: optional string` + - `Direct object { type }` - 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: "direct"` - - `CodeInterpreter object { container, type, allowed_callers }` + - `"direct"` - A tool that runs Python code to help generate a response to a prompt. + - `Program object { caller_id, type }` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `caller_id: string` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + The call ID of the program item that produced this tool call. - - `string` + - `type: "program"` - The container ID. + - `"program"` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `created_by: optional string` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + The ID of the entity that created this tool call. - - `type: "auto"` + - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` - Always `auto`. + The output emitted by an apply patch tool call. - - `"auto"` + - `id: string` - - `file_ids: optional array of string` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - An optional list of uploaded files to make available to your code. + - `call_id: string` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + The unique ID of the apply patch tool call generated by the model. - The memory limit for the code interpreter container. + - `status: "completed" or "failed"` - - `"1g"` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `"4g"` + - `"completed"` - - `"16g"` + - `"failed"` - - `"64g"` + - `type: "apply_patch_call_output"` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + The type of the item. Always `apply_patch_call_output`. - Network access policy for the container. + - `"apply_patch_call_output"` - - `BetaContainerNetworkPolicyDisabled object { type }` + - `agent: optional object { agent_name }` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + The agent that produced this item. - - `type: "code_interpreter"` + - `agent_name: string` - The type of the code interpreter tool. Always `code_interpreter`. + The canonical name of the agent that produced this item. - - `"code_interpreter"` + - `caller: optional object { type } or object { caller_id, type }` - - `allowed_callers: optional array of "direct" or "programmatic"` + The execution context that produced this tool call. - The tool invocation context(s). + - `Direct object { type }` + + - `type: "direct"` - `"direct"` - - `"programmatic"` + - `Program object { caller_id, type }` - - `ProgrammaticToolCalling object { type }` + - `caller_id: string` - - `type: "programmatic_tool_calling"` + The call ID of the program item that produced this tool call. - The type of the tool. Always `programmatic_tool_calling`. + - `type: "program"` - - `"programmatic_tool_calling"` + - `"program"` - - `ImageGeneration object { type, action, background, 9 more }` + - `created_by: optional string` - A tool that generates images using the GPT image models. + The ID of the entity that created this tool call output. - - `type: "image_generation"` + - `output: optional string` - The type of the image generation tool. Always `image_generation`. + Optional textual output returned by the apply patch tool. - - `"image_generation"` + - `McpCall object { id, arguments, name, 7 more }` - - `action: optional "generate" or "edit" or "auto"` + An invocation of a tool on an MCP server. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `id: string` - - `"generate"` + The unique ID of the tool call. - - `"edit"` + - `arguments: string` - - `"auto"` + A JSON string of the arguments passed to the 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 tool that was run. - - `"transparent"` + - `server_label: string` - - `"opaque"` + The label of the MCP server running the tool. - - `"auto"` + - `type: "mcp_call"` - - `input_fidelity: optional "high" or "low"` + The type of the item. Always `mcp_call`. - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + - `"mcp_call"` - - `"high"` + - `agent: optional object { agent_name }` - - `"low"` + The agent that produced this item. - - `input_image_mask: optional object { file_id, image_url }` + - `agent_name: string` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + The canonical name of the agent that produced this item. - - `file_id: optional string` + - `approval_request_id: optional string` - File ID for the mask image. + 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. - - `image_url: optional string` + - `error: optional string` - Base64-encoded mask image. + The error from the tool call, if any. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `output: optional string` - The image generation model to use. Default: `gpt-image-1`. + The output from the tool call. - - `string` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - The image generation model to use. Default: `gpt-image-1`. + - `"in_progress"` - - `"gpt-image-1"` + - `"completed"` - - `"gpt-image-1-mini"` + - `"incomplete"` - - `"gpt-image-1.5"` + - `"calling"` - - `moderation: optional "auto" or "low"` + - `"failed"` - Moderation level for the generated image. Default: `auto`. + - `McpListTools object { id, server_label, tools, 3 more }` - - `"auto"` + A list of tools available on an MCP server. - - `"low"` + - `id: string` - - `output_compression: optional number` + The unique ID of the list. - Compression level for the output image. Default: 100. + - `server_label: string` - - `output_format: optional "png" or "webp" or "jpeg"` + The label of the MCP server. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `tools: array of object { input_schema, name, annotations, description }` - - `"png"` + The tools available on the server. - - `"webp"` + - `input_schema: unknown` - - `"jpeg"` + The JSON schema describing the tool's input. - - `partial_images: optional number` + - `name: string` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The name of the tool. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `annotations: optional unknown` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + Additional annotations about the tool. - - `"low"` + - `description: optional string` - - `"medium"` + The description of the tool. - - `"high"` + - `type: "mcp_list_tools"` - - `"auto"` + The type of the item. Always `mcp_list_tools`. - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `"mcp_list_tools"` - 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`. + - `agent: optional object { agent_name }` - - `string` + The agent that produced this item. - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `agent_name: string` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + The canonical name of the agent that produced this item. - - `"1024x1024"` + - `error: optional string` - - `"1024x1536"` + Error message if the server could not list tools. - - `"1536x1024"` + - `McpApprovalRequest object { id, arguments, name, 3 more }` - - `"auto"` + A request for human approval of a tool invocation. - - `LocalShell object { type }` + - `id: string` - A tool that allows the model to execute shell commands in a local environment. + The unique ID of the approval request. - - `type: "local_shell"` + - `arguments: string` - The type of the local shell tool. Always `local_shell`. + A JSON string of arguments for the tool. - - `"local_shell"` + - `name: string` - - `Shell object { type, allowed_callers, environment }` + The name of the tool to run. - A tool that allows the model to execute shell commands. + - `server_label: string` - - `type: "shell"` + The label of the MCP server making the request. - The type of the shell tool. Always `shell`. + - `type: "mcp_approval_request"` - - `"shell"` + The type of the item. Always `mcp_approval_request`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"mcp_approval_request"` - The tool invocation context(s). + - `agent: optional object { agent_name }` - - `"direct"` + The agent that produced this item. - - `"programmatic"` + - `agent_name: string` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + The canonical name of the agent that produced this item. - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` - - `BetaLocalEnvironment object { type, skills }` + A response to an MCP approval request. + + - `id: string` + + The unique ID of the approval response - - `BetaContainerReference object { container_id, type }` + - `approval_request_id: string` - - `Custom object { name, type, allowed_callers, 3 more }` + The ID of the approval request being answered. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `approve: boolean` - - `name: string` + Whether the request was approved. - The name of the custom tool, used to identify it in tool calls. + - `type: "mcp_approval_response"` - - `type: "custom"` + The type of the item. Always `mcp_approval_response`. - The type of the custom tool. Always `custom`. + - `"mcp_approval_response"` - - `"custom"` + - `agent: optional object { agent_name }` - - `allowed_callers: optional array of "direct" or "programmatic"` + The agent that produced this item. - The tool invocation context(s). + - `agent_name: string` - - `"direct"` + The canonical name of the agent that produced this item. - - `"programmatic"` + - `reason: optional string` - - `defer_loading: optional boolean` + Optional reason for the decision. - Whether this tool should be deferred and discovered via tool search. + - `CustomToolCall object { call_id, input, name, 5 more }` - - `description: optional string` + A call to a custom tool created by the model. - Optional description of the custom tool, used to provide more context. + - `call_id: string` - - `format: optional object { type } or object { definition, syntax, type }` + An identifier used to map this custom tool call to a tool call output. - The input format for the custom tool. Default is unconstrained text. + - `input: string` - - `Text object { type }` + The input for the custom tool call generated by the model. - Unconstrained free-form text. + - `name: string` - - `type: "text"` + The name of the custom tool being called. - Unconstrained text format. Always `text`. + - `type: "custom_tool_call"` - - `"text"` + The type of the custom tool call. Always `custom_tool_call`. - - `Grammar object { definition, syntax, type }` + - `"custom_tool_call"` - A grammar defined by the user. + - `id: optional string` - - `definition: string` + The unique ID of the custom tool call in the OpenAI platform. - The grammar definition. + - `agent: optional object { agent_name }` - - `syntax: "lark" or "regex"` + The agent that produced this item. - The syntax of the grammar definition. One of `lark` or `regex`. + - `agent_name: string` - - `"lark"` + The canonical name of the agent that produced this item. - - `"regex"` + - `caller: optional object { type } or object { caller_id, type }` - - `type: "grammar"` + The execution context that produced this tool call. - Grammar format. Always `grammar`. + - `Direct object { type }` - - `"grammar"` + - `type: "direct"` - - `Namespace object { description, name, tools, type }` + - `"direct"` - Groups function/custom tools under a shared namespace. + - `Program object { caller_id, type }` - - `description: string` + - `caller_id: string` - A description of the namespace shown to the model. + The call ID of the program item that produced this tool call. - - `name: string` + - `type: "program"` - The namespace name used in tool calls (for example, `crm`). + - `"program"` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `namespace: optional string` - The function/custom tools available inside this namespace. + The namespace of the custom tool being called. - - `Function object { name, type, allowed_callers, 5 more }` + - `CustomToolCallOutput object { id, call_id, output, 5 more }` - - `name: string` + - `id: string` - - `type: "function"` + The unique ID of the custom tool call output item. - - `"function"` + - `call_id: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The call ID, used to map this custom tool call output to a custom tool call. - The tool invocation context(s). + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `"direct"` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `"programmatic"` + - `StringOutput = string` - - `defer_loading: optional boolean` + A string of the output of the custom tool call. - Whether this function should be deferred and discovered via tool search. + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `description: optional string` + Text, image, or file output of the custom tool call. - - `output_schema: optional map[unknown]` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + A text input to the model. - - `parameters: optional unknown` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `strict: optional boolean` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - 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. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `Custom object { name, type, allowed_callers, 3 more }` + A file 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) + - `status: "in_progress" or "completed" or "incomplete"` - - `name: string` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The name of the custom tool, used to identify it in tool calls. + - `"in_progress"` - - `type: "custom"` + - `"completed"` - The type of the custom tool. Always `custom`. + - `"incomplete"` - - `"custom"` + - `type: "custom_tool_call_output"` - - `allowed_callers: optional array of "direct" or "programmatic"` + The type of the custom tool call output. Always `custom_tool_call_output`. - The tool invocation context(s). + - `"custom_tool_call_output"` - - `"direct"` + - `agent: optional object { agent_name }` - - `"programmatic"` + The agent that produced this item. - - `defer_loading: optional boolean` + - `agent_name: string` - Whether this tool should be deferred and discovered via tool search. + The canonical name of the agent that produced this item. - - `description: optional string` + - `caller: optional object { type } or object { caller_id, type }` - Optional description of the custom tool, used to provide more context. + The execution context that produced this tool call. - - `format: optional object { type } or object { definition, syntax, type }` + - `Direct object { type }` - The input format for the custom tool. Default is unconstrained text. + - `type: "direct"` - - `Text object { type }` + The caller type. Always `direct`. - Unconstrained free-form text. + - `"direct"` - - `type: "text"` + - `Program object { caller_id, type }` - Unconstrained text format. Always `text`. + - `caller_id: string` - - `"text"` + The call ID of the program item that produced this tool call. - - `Grammar object { definition, syntax, type }` + - `type: "program"` - A grammar defined by the user. + The caller type. Always `program`. - - `definition: string` + - `"program"` - The grammar definition. + - `created_by: optional string` - - `syntax: "lark" or "regex"` + The identifier of the actor that created the item. - The syntax of the grammar definition. One of `lark` or `regex`. + - `parallel_tool_calls: boolean` - - `"lark"` + Whether to allow the model to run tool calls in parallel. - - `"regex"` + - `temperature: number` - - `type: "grammar"` + 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. - Grammar format. Always `grammar`. + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - - `"grammar"` + 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. - - `type: "namespace"` + - `BetaToolChoiceOptions = "none" or "auto" or "required"` - The type of the tool. Always `namespace`. + Controls which (if any) tool is called by the model. - - `"namespace"` + `none` means the model will not call any tool and instead generates a message. - - `ToolSearch object { type, description, execution, parameters }` + `auto` means the model can pick between generating a message or calling one or + more tools. - Hosted or BYOT tool search configuration for deferred tools. + `required` means the model must call one or more tools. - - `type: "tool_search"` + - `"none"` - The type of the tool. Always `tool_search`. + - `"auto"` - - `"tool_search"` + - `"required"` - - `description: optional string` + - `BetaToolChoiceAllowed object { mode, tools, type }` - Description shown to the model for a client-executed tool search tool. + Constrains the tools available to the model to a pre-defined set. - - `execution: optional "server" or "client"` + - `mode: "auto" or "required"` - Whether tool search is executed by the server or by the client. + Constrains the tools available to the model to a pre-defined set. - - `"server"` + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `"client"` + `required` requires the model to call one or more of the allowed tools. - - `parameters: optional unknown` + - `"auto"` - Parameter schema for a client-executed tool search tool. + - `"required"` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `tools: array of map[unknown]` - 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 list of tool definitions that the model should be allowed to call. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + For the Responses API, the list of tool definitions might look like: - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `"web_search_preview"` + - `type: "allowed_tools"` - - `"web_search_preview_2025_03_11"` + Allowed tool configuration type. Always `allowed_tools`. - - `search_content_types: optional array of "text" or "image"` + - `"allowed_tools"` - - `"text"` + - `BetaToolChoiceTypes object { type }` - - `"image"` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](/docs/guides/tools). - - `search_context_size: optional "low" or "medium" or "high"` + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The type of hosted tool the model should to use. Learn more about + [built-in tools](/docs/guides/tools). - - `"low"` + Allowed values are: - - `"medium"` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `"high"` + - `"file_search"` - - `user_location: optional object { type, city, country, 2 more }` + - `"web_search_preview"` - The user's location. + - `"computer"` - - `type: "approximate"` + - `"computer_use_preview"` - The type of location approximation. Always `approximate`. + - `"computer_use"` - - `"approximate"` + - `"web_search_preview_2025_03_11"` - - `city: optional string` + - `"image_generation"` - Free text input for the city of the user, e.g. `San Francisco`. + - `"code_interpreter"` - - `country: optional string` + - `BetaToolChoiceFunction object { name, type }` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + Use this option to force the model to call a specific function. - - `region: optional string` + - `name: string` - Free text input for the region of the user, e.g. `California`. + The name of the function to call. - - `timezone: optional string` + - `type: "function"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + For function calling, the type is always `function`. - - `ApplyPatch object { type, allowed_callers }` + - `"function"` - Allows the assistant to create, delete, or update files using unified diffs. + - `BetaToolChoiceMcp object { server_label, type, name }` - - `type: "apply_patch"` + Use this option to force the model to call a specific tool on a remote MCP server. - The type of the tool. Always `apply_patch`. + - `server_label: string` - - `"apply_patch"` + The label of the MCP server to use. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "mcp"` - The tool invocation context(s). + For MCP tools, the type is always `mcp`. - - `"direct"` + - `"mcp"` - - `"programmatic"` + - `name: optional string` - - `type: "tool_search_output"` + The name of the tool to call on the server. - The type of the item. Always `tool_search_output`. + - `BetaToolChoiceCustom object { name, type }` - - `"tool_search_output"` + Use this option to force the model to call a specific custom tool. - - `agent: optional object { agent_name }` + - `name: string` - The agent that produced this item. + The name of the custom tool to call. - - `agent_name: string` + - `type: "custom"` - The canonical name of the agent that produced this item. + For custom tool calling, the type is always `custom`. - - `created_by: optional string` + - `"custom"` - The identifier of the actor that created the item. + - `BetaSpecificProgrammaticToolCallingParam object { type }` - - `AdditionalTools object { id, role, tools, 2 more }` + - `type: "programmatic_tool_calling"` - - `id: string` + The tool to call. Always `programmatic_tool_calling`. - The unique ID of the additional tools item. + - `"programmatic_tool_calling"` - - `role: "unknown" or "user" or "assistant" or 5 more` + - `BetaToolChoiceApplyPatch object { type }` - The role that provided the additional tools. + Forces the model to call the apply_patch tool when executing a tool call. - - `"unknown"` + - `type: "apply_patch"` - - `"user"` + The tool to call. Always `apply_patch`. - - `"assistant"` + - `"apply_patch"` - - `"system"` + - `BetaToolChoiceShell object { type }` - - `"critic"` + Forces the model to call the shell tool when a tool call is required. - - `"discriminator"` + - `type: "shell"` - - `"developer"` + The tool to call. Always `shell`. - - `"tool"` + - `"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` - The additional tool definitions made available at this item. + 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. + + We support the following categories of tools: + + - **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. - `Function object { name, parameters, strict, 5 more }` @@ -166726,827 +165796,1503 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `user_location: optional object { type, city, country, 2 more }` - The user's location. + 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 BetaResponsePrompt` + + 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 BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + + 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` + + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](/docs/guides/vision). + + - `BetaResponseInputFile 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 object { context, effort, generate_summary, 2 more }` + + **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 "none" or "minimal" or "low" or 4 more` + + 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 BetaResponseStatus` + + 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 BetaResponseTextConfig` + + 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 BetaResponseFormatTextConfig` + + 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. + + - `Text object { type }` + + Default response format. Used to generate text responses. + + - `type: "text"` + + The type of response format being defined. Always `text`. + + - `"text"` + + - `BetaResponseFormatTextJSONSchemaConfig 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). + + - `JSONObject 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 BetaResponseUsage` + + 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). + + - `sequence_number: number` + + The sequence number for this event. + + - `type: "response.queued"` + + The type of the event. Always 'response.queued'. + + - `"response.queued"` + + - `agent: optional object { agent_name }` + + The agent that owns this multi-agent streaming event. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + +### Beta Response Reasoning Summary Part Added Event + +- `BetaResponseReasoningSummaryPartAddedEvent object { item_id, output_index, part, 4 more }` + + Emitted when a new reasoning summary part is added. + + - `item_id: string` + + The ID of the item this summary part is associated with. + + - `output_index: number` + + The index of the output item this summary part is associated with. + + - `part: object { text, type }` + + The summary part that was added. + + - `text: string` + + The text of the summary part. + + - `type: "summary_text"` + + The type of the summary part. Always `summary_text`. + + - `"summary_text"` + + - `sequence_number: number` + + The sequence number of this event. + + - `summary_index: number` + + The index of the summary part within the reasoning summary. + + - `type: "response.reasoning_summary_part.added"` + + The type of the event. Always `response.reasoning_summary_part.added`. + + - `"response.reasoning_summary_part.added"` + + - `agent: optional object { agent_name }` + + The agent that owns this multi-agent streaming event. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + +### Beta Response Reasoning Summary Part Done Event + +- `BetaResponseReasoningSummaryPartDoneEvent object { item_id, output_index, part, 5 more }` + + Emitted when a reasoning summary part is completed. + + - `item_id: string` + + The ID of the item this summary part is associated with. + + - `output_index: number` + + The index of the output item this summary part is associated with. + + - `part: object { text, type }` - - `type: "approximate"` + The completed summary part. - The type of location approximation. Always `approximate`. + - `text: string` - - `"approximate"` + The text of the summary part. - - `city: optional string` + - `type: "summary_text"` - Free text input for the city of the user, e.g. `San Francisco`. + The type of the summary part. Always `summary_text`. - - `country: optional string` + - `"summary_text"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `sequence_number: number` - - `region: optional string` + The sequence number of this event. - Free text input for the region of the user, e.g. `California`. + - `summary_index: number` - - `timezone: optional string` + The index of the summary part within the reasoning summary. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `type: "response.reasoning_summary_part.done"` - - `ApplyPatch object { type, allowed_callers }` + The type of the event. Always `response.reasoning_summary_part.done`. - Allows the assistant to create, delete, or update files using unified diffs. + - `"response.reasoning_summary_part.done"` - - `type: "apply_patch"` + - `agent: optional object { agent_name }` - The type of the tool. Always `apply_patch`. + The agent that owns this multi-agent streaming event. - - `"apply_patch"` + - `agent_name: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The canonical name of the agent that produced this item. - The tool invocation context(s). + - `status: optional "incomplete"` - - `"direct"` + The completion status of the summary part. Omitted when the part completed + normally and set to `incomplete` when generation was interrupted. - - `"programmatic"` + - `"incomplete"` - - `type: "additional_tools"` +### Beta Response Reasoning Summary Text Delta Event - The type of the item. Always `additional_tools`. +- `BetaResponseReasoningSummaryTextDeltaEvent object { delta, item_id, output_index, 4 more }` - - `"additional_tools"` + Emitted when a delta is added to a reasoning summary text. - - `agent: optional object { agent_name }` + - `delta: string` - The agent that produced this item. + The text delta that was added to the summary. - - `agent_name: string` + - `item_id: string` - The canonical name of the agent that produced this item. + The ID of the item this summary text delta is associated with. - - `Compaction object { id, encrypted_content, type, 2 more }` + - `output_index: number` - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + The index of the output item this summary text delta is associated with. - - `id: string` + - `sequence_number: number` - The unique ID of the compaction item. + The sequence number of this event. - - `encrypted_content: string` + - `summary_index: number` - The encrypted content that was produced by compaction. + The index of the summary part within the reasoning summary. - - `type: "compaction"` + - `type: "response.reasoning_summary_text.delta"` - The type of the item. Always `compaction`. + The type of the event. Always `response.reasoning_summary_text.delta`. - - `"compaction"` + - `"response.reasoning_summary_text.delta"` - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `created_by: optional string` - - The identifier of the actor that created the item. +### Beta Response Reasoning Summary Text Done Event - - `ImageGenerationCall object { id, result, status, 2 more }` +- `BetaResponseReasoningSummaryTextDoneEvent object { item_id, output_index, sequence_number, 4 more }` - An image generation request made by the model. + Emitted when a reasoning summary text is completed. - - `id: string` + - `item_id: string` - The unique ID of the image generation call. + The ID of the item this summary text is associated with. - - `result: string` + - `output_index: number` - The generated image encoded in base64. + The index of the output item this summary text is associated with. - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `sequence_number: number` - The status of the image generation call. + The sequence number of this event. - - `"in_progress"` + - `summary_index: number` - - `"completed"` + The index of the summary part within the reasoning summary. - - `"generating"` + - `text: string` - - `"failed"` + The full text of the completed reasoning summary. - - `type: "image_generation_call"` + - `type: "response.reasoning_summary_text.done"` - The type of the image generation call. Always `image_generation_call`. + The type of the event. Always `response.reasoning_summary_text.done`. - - `"image_generation_call"` + - `"response.reasoning_summary_text.done"` - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `CodeInterpreterCall object { id, code, container_id, 4 more }` +### Beta Response Reasoning Text Delta Event - A tool call to run code. +- `BetaResponseReasoningTextDeltaEvent object { content_index, delta, item_id, 4 more }` - - `id: string` + Emitted when a delta is added to a reasoning text. - The unique ID of the code interpreter tool call. + - `content_index: number` - - `code: string` + The index of the reasoning content part this delta is associated with. - The code to run, or null if not available. + - `delta: string` - - `container_id: string` + The text delta that was added to the reasoning content. - The ID of the container used to run the code. + - `item_id: string` - - `outputs: array of object { logs, type } or object { type, url }` + The ID of the item this reasoning text delta is associated with. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `output_index: number` - - `Logs object { logs, type }` + The index of the output item this reasoning text delta is associated with. - The logs output from the code interpreter. + - `sequence_number: number` - - `logs: string` + The sequence number of this event. - The logs output from the code interpreter. + - `type: "response.reasoning_text.delta"` - - `type: "logs"` + The type of the event. Always `response.reasoning_text.delta`. - The type of the output. Always `logs`. + - `"response.reasoning_text.delta"` - - `"logs"` + - `agent: optional object { agent_name }` - - `Image object { type, url }` + The agent that owns this multi-agent streaming event. - The image output from the code interpreter. + - `agent_name: string` - - `type: "image"` + The canonical name of the agent that produced this item. - The type of the output. Always `image`. +### Beta Response Reasoning Text Done Event - - `"image"` +- `BetaResponseReasoningTextDoneEvent object { content_index, item_id, output_index, 4 more }` - - `url: string` + Emitted when a reasoning text is completed. - The URL of the image output from the code interpreter. + - `content_index: number` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + The index of the reasoning content part. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `item_id: string` - - `"in_progress"` + The ID of the item this reasoning text is associated with. - - `"completed"` + - `output_index: number` - - `"incomplete"` + The index of the output item this reasoning text is associated with. - - `"interpreting"` + - `sequence_number: number` - - `"failed"` + The sequence number of this event. - - `type: "code_interpreter_call"` + - `text: string` - The type of the code interpreter tool call. Always `code_interpreter_call`. + The full text of the completed reasoning content. - - `"code_interpreter_call"` + - `type: "response.reasoning_text.done"` + + The type of the event. Always `response.reasoning_text.done`. + + - `"response.reasoning_text.done"` - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `LocalShellCall object { id, action, call_id, 3 more }` +### Beta Response Refusal Delta Event - A tool call to run a command on the local shell. +- `BetaResponseRefusalDeltaEvent object { content_index, delta, item_id, 4 more }` - - `id: string` + Emitted when there is a partial refusal text. - The unique ID of the local shell call. + - `content_index: number` - - `action: object { command, env, type, 3 more }` + The index of the content part that the refusal text is added to. - Execute a shell command on the server. + - `delta: string` - - `command: array of string` + The refusal text that is added. - The command to run. + - `item_id: string` - - `env: map[string]` + The ID of the output item that the refusal text is added to. - Environment variables to set for the command. + - `output_index: number` - - `type: "exec"` + The index of the output item that the refusal text is added to. - The type of the local shell action. Always `exec`. + - `sequence_number: number` - - `"exec"` + The sequence number of this event. - - `timeout_ms: optional number` + - `type: "response.refusal.delta"` - Optional timeout in milliseconds for the command. + The type of the event. Always `response.refusal.delta`. - - `user: optional string` + - `"response.refusal.delta"` - Optional user to run the command as. + - `agent: optional object { agent_name }` - - `working_directory: optional string` + The agent that owns this multi-agent streaming event. - Optional working directory to run the command in. + - `agent_name: string` - - `call_id: string` + The canonical name of the agent that produced this item. - The unique ID of the local shell tool call generated by the model. +### Beta Response Refusal Done Event - - `status: "in_progress" or "completed" or "incomplete"` +- `BetaResponseRefusalDoneEvent object { content_index, item_id, output_index, 4 more }` - The status of the local shell call. + Emitted when refusal text is finalized. - - `"in_progress"` + - `content_index: number` - - `"completed"` + The index of the content part that the refusal text is finalized. - - `"incomplete"` + - `item_id: string` - - `type: "local_shell_call"` + The ID of the output item that the refusal text is finalized. - The type of the local shell call. Always `local_shell_call`. + - `output_index: number` - - `"local_shell_call"` + The index of the output item that the refusal text is finalized. - - `agent: optional object { agent_name }` + - `refusal: string` - The agent that produced this item. + The refusal text that is finalized. - - `agent_name: string` + - `sequence_number: number` - The canonical name of the agent that produced this item. + The sequence number of this event. - - `LocalShellCallOutput object { id, output, type, 2 more }` + - `type: "response.refusal.done"` - The output of a local shell tool call. + The type of the event. Always `response.refusal.done`. - - `id: string` + - `"response.refusal.done"` - The unique ID of the local shell tool call generated by the model. + - `agent: optional object { agent_name }` - - `output: string` + The agent that owns this multi-agent streaming event. - A JSON string of the output of the local shell tool call. + - `agent_name: string` - - `type: "local_shell_call_output"` + The canonical name of the agent that produced this item. - The type of the local shell tool call output. Always `local_shell_call_output`. +### Beta Response Status - - `"local_shell_call_output"` +- `BetaResponseStatus = "completed" or "failed" or "in_progress" or 3 more` - - `agent: optional object { agent_name }` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - The agent that produced this item. + - `"completed"` - - `agent_name: string` + - `"failed"` - The canonical name of the agent that produced this item. + - `"in_progress"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"cancelled"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `"queued"` - - `"in_progress"` + - `"incomplete"` - - `"completed"` +### Beta Response Stream Event - - `"incomplete"` +- `BetaResponseStreamEvent = BetaResponseAudioDeltaEvent or BetaResponseAudioDoneEvent or BetaResponseAudioTranscriptDeltaEvent or 50 more` - - `ShellCall object { id, action, call_id, 6 more }` + Emitted when there is a partial audio response. - A tool call that executes one or more shell commands in a managed environment. + - `BetaResponseAudioDeltaEvent object { delta, sequence_number, type, agent }` - - `id: string` + Emitted when there is a partial audio response. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `delta: string` - - `action: object { commands, max_output_length, timeout_ms }` + A chunk of Base64 encoded response audio bytes. - The shell commands and limits that describe how to run the tool call. + - `sequence_number: number` - - `commands: array of string` + A sequence number for this chunk of the stream response. - - `max_output_length: number` + - `type: "response.audio.delta"` - Optional maximum number of characters to return from each command. + The type of the event. Always `response.audio.delta`. - - `timeout_ms: number` + - `"response.audio.delta"` - Optional timeout in milliseconds for the commands. + - `agent: optional object { agent_name }` - - `call_id: string` + The agent that owns this multi-agent streaming event. - The unique ID of the shell tool call generated by the model. + - `agent_name: string` - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + The canonical name of the agent that produced this item. - Represents the use of a local environment to perform shell actions. + - `BetaResponseAudioDoneEvent object { sequence_number, type, agent }` - - `BetaResponseLocalEnvironment object { type }` + Emitted when the audio response is complete. - Represents the use of a local environment to perform shell actions. + - `sequence_number: number` - - `type: "local"` + The sequence number of the delta. - The environment type. Always `local`. + - `type: "response.audio.done"` - - `"local"` + The type of the event. Always `response.audio.done`. - - `BetaResponseContainerReference object { container_id, type }` + - `"response.audio.done"` - Represents a container created with /v1/containers. + - `agent: optional object { agent_name }` - - `container_id: string` + The agent that owns this multi-agent streaming event. - - `type: "container_reference"` + - `agent_name: string` - The environment type. Always `container_reference`. + The canonical name of the agent that produced this item. - - `"container_reference"` + - `BetaResponseAudioTranscriptDeltaEvent object { delta, sequence_number, type, agent }` - - `status: "in_progress" or "completed" or "incomplete"` + Emitted when there is a partial transcript of audio. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `delta: string` - - `"in_progress"` + The partial transcript of the audio response. - - `"completed"` + - `sequence_number: number` - - `"incomplete"` + The sequence number of this event. - - `type: "shell_call"` + - `type: "response.audio.transcript.delta"` - The type of the item. Always `shell_call`. + The type of the event. Always `response.audio.transcript.delta`. - - `"shell_call"` + - `"response.audio.transcript.delta"` - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` + - `BetaResponseAudioTranscriptDoneEvent object { sequence_number, type, agent }` - The execution context that produced this tool call. + Emitted when the full audio transcript is completed. - - `Direct object { type }` + - `sequence_number: number` - - `type: "direct"` + The sequence number of this event. - - `"direct"` + - `type: "response.audio.transcript.done"` - - `Program object { caller_id, type }` + The type of the event. Always `response.audio.transcript.done`. - - `caller_id: string` + - `"response.audio.transcript.done"` - The call ID of the program item that produced this tool call. + - `agent: optional object { agent_name }` - - `type: "program"` + The agent that owns this multi-agent streaming event. - - `"program"` + - `agent_name: string` - - `created_by: optional string` + The canonical name of the agent that produced this item. - The ID of the entity that created this tool call. + - `BetaResponseCodeInterpreterCallCodeDeltaEvent object { delta, item_id, output_index, 3 more }` - - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` + Emitted when a partial code snippet is streamed by the code interpreter. - The output of a shell tool call that was emitted. + - `delta: string` - - `id: string` + The partial code snippet being streamed by the code interpreter. - The unique ID of the shell call output. Populated when this item is returned via API. + - `item_id: string` - - `call_id: string` + The unique identifier of the code interpreter tool call item. - The unique ID of the shell tool call generated by the model. + - `output_index: number` - - `max_output_length: number` + The index of the output item in the response for which the code is being streamed. - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `sequence_number: number` - - `output: array of object { outcome, stderr, stdout, created_by }` + The sequence number of this event, used to order streaming events. - An array of shell call output contents + - `type: "response.code_interpreter_call_code.delta"` - - `outcome: object { type } or object { exit_code, type }` + The type of the event. Always `response.code_interpreter_call_code.delta`. - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `"response.code_interpreter_call_code.delta"` - - `Timeout object { type }` + - `agent: optional object { agent_name }` - Indicates that the shell call exceeded its configured time limit. + The agent that owns this multi-agent streaming event. - - `type: "timeout"` + - `agent_name: string` - The outcome type. Always `timeout`. + The canonical name of the agent that produced this item. - - `"timeout"` + - `BetaResponseCodeInterpreterCallCodeDoneEvent object { code, item_id, output_index, 3 more }` - - `Exit object { exit_code, type }` + Emitted when the code snippet is finalized by the code interpreter. - Indicates that the shell commands finished and returned an exit code. + - `code: string` - - `exit_code: number` + The final code snippet output by the code interpreter. - Exit code from the shell process. + - `item_id: string` - - `type: "exit"` + The unique identifier of the code interpreter tool call item. - The outcome type. Always `exit`. + - `output_index: number` - - `"exit"` + The index of the output item in the response for which the code is finalized. - - `stderr: string` + - `sequence_number: number` - The standard error output that was captured. + The sequence number of this event, used to order streaming events. - - `stdout: string` + - `type: "response.code_interpreter_call_code.done"` - The standard output that was captured. + The type of the event. Always `response.code_interpreter_call_code.done`. - - `created_by: optional string` + - `"response.code_interpreter_call_code.done"` - The identifier of the actor that created the item. + - `agent: optional object { agent_name }` - - `status: "in_progress" or "completed" or "incomplete"` + The agent that owns this multi-agent streaming event. - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `agent_name: string` - - `"in_progress"` + The canonical name of the agent that produced this item. - - `"completed"` + - `BetaResponseCodeInterpreterCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - - `"incomplete"` + Emitted when the code interpreter call is completed. - - `type: "shell_call_output"` + - `item_id: string` - The type of the shell call output. Always `shell_call_output`. + The unique identifier of the code interpreter tool call item. - - `"shell_call_output"` + - `output_index: number` - - `agent: optional object { agent_name }` + The index of the output item in the response for which the code interpreter call is completed. - The agent that produced this item. + - `sequence_number: number` - - `agent_name: string` + The sequence number of this event, used to order streaming events. - The canonical name of the agent that produced this item. + - `type: "response.code_interpreter_call.completed"` - - `caller: optional object { type } or object { caller_id, type }` + The type of the event. Always `response.code_interpreter_call.completed`. - The execution context that produced this tool call. + - `"response.code_interpreter_call.completed"` - - `Direct object { type }` + - `agent: optional object { agent_name }` - - `type: "direct"` + The agent that owns this multi-agent streaming event. - - `"direct"` + - `agent_name: string` - - `Program object { caller_id, type }` + The canonical name of the agent that produced this item. - - `caller_id: string` + - `BetaResponseCodeInterpreterCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` - The call ID of the program item that produced this tool call. + Emitted when a code interpreter call is in progress. - - `type: "program"` + - `item_id: string` - - `"program"` + The unique identifier of the code interpreter tool call item. - - `created_by: optional string` + - `output_index: number` - The identifier of the actor that created the item. + The index of the output item in the response for which the code interpreter call is in progress. - - `ApplyPatchCall object { id, call_id, operation, 5 more }` + - `sequence_number: number` - A tool call that applies file diffs by creating, deleting, or updating files. + The sequence number of this event, used to order streaming events. - - `id: string` + - `type: "response.code_interpreter_call.in_progress"` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + The type of the event. Always `response.code_interpreter_call.in_progress`. - - `call_id: string` + - `"response.code_interpreter_call.in_progress"` - The unique ID of the apply patch tool call generated by the model. + - `agent: optional object { agent_name }` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + The agent that owns this multi-agent streaming event. - One of the create_file, delete_file, or update_file operations applied via apply_patch. + - `agent_name: string` - - `CreateFile object { diff, path, type }` + The canonical name of the agent that produced this item. - Instruction describing how to create a file via the apply_patch tool. + - `BetaResponseCodeInterpreterCallInterpretingEvent object { item_id, output_index, sequence_number, 2 more }` - - `diff: string` + Emitted when the code interpreter is actively interpreting the code snippet. - Diff to apply. + - `item_id: string` - - `path: string` + The unique identifier of the code interpreter tool call item. - Path of the file to create. + - `output_index: number` - - `type: "create_file"` + The index of the output item in the response for which the code interpreter is interpreting code. - Create a new file with the provided diff. + - `sequence_number: number` - - `"create_file"` + The sequence number of this event, used to order streaming events. - - `DeleteFile object { path, type }` + - `type: "response.code_interpreter_call.interpreting"` - Instruction describing how to delete a file via the apply_patch tool. + The type of the event. Always `response.code_interpreter_call.interpreting`. - - `path: string` + - `"response.code_interpreter_call.interpreting"` - Path of the file to delete. + - `agent: optional object { agent_name }` - - `type: "delete_file"` + The agent that owns this multi-agent streaming event. - Delete the specified file. + - `agent_name: string` - - `"delete_file"` + The canonical name of the agent that produced this item. - - `UpdateFile object { diff, path, type }` + - `BetaResponseCompletedEvent object { response, sequence_number, type, agent }` - Instruction describing how to update a file via the apply_patch tool. + Emitted when the model response is complete. - - `diff: string` + - `response: BetaResponse` - Diff to apply. + Properties of the completed response. - - `path: string` + - `id: string` - Path of the file to update. + Unique identifier for this Response. - - `type: "update_file"` + - `created_at: number` - Update an existing file with the provided diff. + Unix timestamp (in seconds) of when this Response was created. - - `"update_file"` + - `error: BetaResponseError` - - `status: "in_progress" or "completed"` + An error object returned when the model fails to generate a Response. - The status of the apply patch tool call. One of `in_progress` or `completed`. + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 17 more` - - `"in_progress"` + The error code for the response. - - `"completed"` + - `"server_error"` - - `type: "apply_patch_call"` + - `"rate_limit_exceeded"` - The type of the item. Always `apply_patch_call`. + - `"invalid_prompt"` - - `"apply_patch_call"` + - `"data_residency_mismatch"` - - `agent: optional object { agent_name }` + - `"bio_policy"` - The agent that produced this item. + - `"vector_store_timeout"` - - `agent_name: string` + - `"invalid_image"` - The canonical name of the agent that produced this item. + - `"invalid_image_format"` - - `caller: optional object { type } or object { caller_id, type }` + - `"invalid_base64_image"` - The execution context that produced this tool call. + - `"invalid_image_url"` - - `Direct object { type }` + - `"image_too_large"` - - `type: "direct"` + - `"image_too_small"` - - `"direct"` + - `"image_parse_error"` - - `Program object { caller_id, type }` + - `"image_content_policy_violation"` - - `caller_id: string` + - `"invalid_image_mode"` - The call ID of the program item that produced this tool call. + - `"image_file_too_large"` - - `type: "program"` + - `"unsupported_image_media_type"` - - `"program"` + - `"empty_image_file"` - - `created_by: optional string` + - `"failed_to_download_image"` - The ID of the entity that created this tool call. + - `"image_file_not_found"` - - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` + - `message: string` - The output emitted by an apply patch tool call. + A human-readable description of the error. - - `id: string` + - `incomplete_details: object { reason }` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + Details about why the response is incomplete. - - `call_id: string` + - `reason: optional "max_output_tokens" or "content_filter"` - The unique ID of the apply patch tool call generated by the model. + The reason why the response is incomplete. - - `status: "completed" or "failed"` + - `"max_output_tokens"` - The status of the apply patch tool call output. One of `completed` or `failed`. + - `"content_filter"` - - `"completed"` + - `instructions: string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - - `"failed"` + A system (or developer) message inserted into the model's context. - - `type: "apply_patch_call_output"` + 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. - The type of the item. Always `apply_patch_call_output`. + - `string` - - `"apply_patch_call_output"` + A text input to the model, equivalent to a text input with the + `developer` role. - - `agent: optional object { agent_name }` + - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - The agent that produced this item. + A list of one or many input items to the model, containing + different content types. - - `agent_name: string` + - `BetaEasyInputMessage object { content, role, phase, type }` - The canonical name of the agent that produced this 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. Messages with the + `assistant` role are presumed to have been generated by the model in previous + interactions. - - `caller: optional object { type } or object { caller_id, type }` + - `content: string or BetaResponseInputMessageContentList` - The execution context that produced this tool call. + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `Direct object { type }` + - `TextInput = string` - - `type: "direct"` + A text input to the model. - - `"direct"` + - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` - - `Program object { caller_id, type }` + A list of one or many input items to the model, containing different content + types. - - `caller_id: string` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - The call ID of the program item that produced this tool call. + A text input to the model. - - `type: "program"` + - `text: string` - - `"program"` + The text input to the model. - - `created_by: optional string` + - `type: "input_text"` - The ID of the entity that created this tool call output. + The type of the input item. Always `input_text`. - - `output: optional string` + - `"input_text"` - Optional textual output returned by the apply patch tool. + - `prompt_cache_breakpoint: optional object { mode }` - - `McpCall object { id, arguments, name, 7 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. - An invocation of a tool on an MCP server. + - `mode: "explicit"` - - `id: string` + The breakpoint mode. Always `explicit`. - The unique ID of the tool call. + - `"explicit"` - - `arguments: string` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - A JSON string of the arguments passed to the tool. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `name: string` + - `detail: "low" or "high" or "auto" or "original"` - The name of the tool that was run. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `server_label: string` + - `"low"` - The label of the MCP server running the tool. + - `"high"` - - `type: "mcp_call"` + - `"auto"` - The type of the item. Always `mcp_call`. + - `"original"` - - `"mcp_call"` + - `type: "input_image"` - - `agent: optional object { agent_name }` + The type of the input item. Always `input_image`. - The agent that produced this item. + - `"input_image"` - - `agent_name: string` + - `file_id: optional string` - The canonical name of the agent that produced this item. + The ID of the file to be sent to the model. - - `approval_request_id: optional string` + - `image_url: 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. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `error: optional string` + - `prompt_cache_breakpoint: optional object { mode }` - The error from the tool call, if any. + 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. - - `output: optional string` + - `mode: "explicit"` - The output from the tool call. + The breakpoint mode. Always `explicit`. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `"explicit"` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `"in_progress"` + A file input to the model. - - `"completed"` + - `type: "input_file"` - - `"incomplete"` + The type of the input item. Always `input_file`. - - `"calling"` + - `"input_file"` - - `"failed"` + - `detail: optional "auto" or "low" or "high"` - - `McpListTools object { id, server_label, tools, 3 more }` + 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`. - A list of tools available on an MCP server. + - `"auto"` - - `id: string` + - `"low"` - The unique ID of the list. + - `"high"` - - `server_label: string` + - `file_data: optional string` - The label of the MCP server. + The content of the file to be sent to the model. - - `tools: array of object { input_schema, name, annotations, description }` + - `file_id: optional string` - The tools available on the server. + The ID of the file to be sent to the model. - - `input_schema: unknown` + - `file_url: optional string` - The JSON schema describing the tool's input. + The URL of the file to be sent to the model. - - `name: string` + - `filename: optional string` - The name of the tool. + The name of the file to be sent to the model. - - `annotations: optional unknown` + - `prompt_cache_breakpoint: optional object { mode }` - Additional annotations about the tool. + 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"` - The description of the tool. + The breakpoint mode. Always `explicit`. - - `type: "mcp_list_tools"` + - `"explicit"` - The type of the item. Always `mcp_list_tools`. + - `role: "user" or "assistant" or "system" or "developer"` - - `"mcp_list_tools"` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `agent: optional object { agent_name }` + - `"user"` - The agent that produced this item. + - `"assistant"` - - `agent_name: string` + - `"system"` - The canonical name of the agent that produced this item. + - `"developer"` - - `error: optional string` + - `phase: optional "commentary" or "final_answer"` - Error message if the server could not list tools. + 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. - - `McpApprovalRequest object { id, arguments, name, 3 more }` + - `"commentary"` - A request for human approval of a tool invocation. + - `"final_answer"` - - `id: string` + - `type: optional "message"` - The unique ID of the approval request. + The type of the message input. Always `message`. - - `arguments: string` + - `"message"` - A JSON string of arguments for the tool. + - `Message object { content, role, agent, 2 more }` - - `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. - The name of the tool to run. + - `content: BetaResponseInputMessageContentList` - - `server_label: string` + A list of one or many input items to the model, containing different content + types. - The label of the MCP server making the request. + - `role: "user" or "system" or "developer"` - - `type: "mcp_approval_request"` + The role of the message input. One of `user`, `system`, or `developer`. - The type of the item. Always `mcp_approval_request`. + - `"user"` - - `"mcp_approval_request"` + - `"system"` + + - `"developer"` - `agent: optional object { agent_name }` @@ -167556,1365 +167302,1316 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` + - `status: optional "in_progress" or "completed" or "incomplete"` - A response to an MCP approval request. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `id: string` + - `"in_progress"` - The unique ID of the approval response + - `"completed"` - - `approval_request_id: string` + - `"incomplete"` - The ID of the approval request being answered. + - `type: optional "message"` - - `approve: boolean` + The type of the message input. Always set to `message`. - Whether the request was approved. + - `"message"` - - `type: "mcp_approval_response"` + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - The type of the item. Always `mcp_approval_response`. + An output message from the model. - - `"mcp_approval_response"` + - `id: string` - - `agent: optional object { agent_name }` + The unique ID of the output message. - The agent that produced this item. + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - - `agent_name: string` + The content of the output message. - The canonical name of the agent that produced this item. + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - - `reason: optional string` + A text output from the model. - Optional reason for the decision. + - `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 }` - - `CustomToolCall object { call_id, input, name, 5 more }` + The annotations of the text output. - A call to a custom tool created by the model. + - `FileCitation object { file_id, filename, index, type }` - - `call_id: string` + A citation to a file. - An identifier used to map this custom tool call to a tool call output. + - `file_id: string` - - `input: string` + The ID of the file. - The input for the custom tool call generated by the model. + - `filename: string` - - `name: string` + The filename of the file cited. - The name of the custom tool being called. + - `index: number` - - `type: "custom_tool_call"` + The index of the file in the list of files. - The type of the custom tool call. Always `custom_tool_call`. + - `type: "file_citation"` - - `"custom_tool_call"` + The type of the file citation. Always `file_citation`. - - `id: optional string` + - `"file_citation"` - The unique ID of the custom tool call in the OpenAI platform. + - `URLCitation object { end_index, start_index, title, 2 more }` - - `agent: optional object { agent_name }` + A citation for a web resource used to generate a model response. - The agent that produced this item. + - `end_index: number` - - `agent_name: string` + The index of the last character of the URL citation in the message. - The canonical name of the agent that produced this item. + - `start_index: number` - - `caller: optional object { type } or object { caller_id, type }` + The index of the first character of the URL citation in the message. - The execution context that produced this tool call. + - `title: string` - - `Direct object { type }` + The title of the web resource. - - `type: "direct"` + - `type: "url_citation"` - - `"direct"` + The type of the URL citation. Always `url_citation`. - - `Program object { caller_id, type }` + - `"url_citation"` - - `caller_id: string` + - `url: string` - The call ID of the program item that produced this tool call. + The URL of the web resource. - - `type: "program"` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - - `"program"` + A citation for a container file used to generate a model response. - - `namespace: optional string` + - `container_id: string` - The namespace of the custom tool being called. + The ID of the container file. - - `CustomToolCallOutput object { id, call_id, output, 5 more }` + - `end_index: number` - - `id: string` + The index of the last character of the container file citation in the message. - The unique ID of the custom tool call output item. + - `file_id: string` - - `call_id: string` + The ID of the file. - The call ID, used to map this custom tool call output to a custom tool call. + - `filename: string` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The filename of the container file cited. - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `start_index: number` - - `StringOutput = string` + The index of the first character of the container file citation in the message. - A string of the output of the custom tool call. + - `type: "container_file_citation"` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The type of the container file citation. Always `container_file_citation`. - Text, image, or file output of the custom tool call. + - `"container_file_citation"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `FilePath object { file_id, index, type }` - A text input to the model. + A path to a file. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `file_id: string` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + The ID of the file. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `index: number` - A file input to the model. + The index of the file in the list of files. - - `status: "in_progress" or "completed" or "incomplete"` + - `type: "file_path"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The type of the file path. Always `file_path`. - - `"in_progress"` + - `"file_path"` - - `"completed"` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - - `"incomplete"` + - `token: string` - - `type: "custom_tool_call_output"` + - `bytes: array of number` - The type of the custom tool call output. Always `custom_tool_call_output`. + - `logprob: number` - - `"custom_tool_call_output"` + - `top_logprobs: array of object { token, bytes, logprob }` - - `agent: optional object { agent_name }` + - `token: string` - The agent that produced this item. + - `bytes: array of number` - - `agent_name: string` + - `logprob: number` - The canonical name of the agent that produced this item. + - `text: string` - - `caller: optional object { type } or object { caller_id, type }` + The text output from the model. - The execution context that produced this tool call. + - `type: "output_text"` - - `Direct object { type }` + The type of the output text. Always `output_text`. - - `type: "direct"` + - `"output_text"` - The caller type. Always `direct`. + - `BetaResponseOutputRefusal object { refusal, type }` - - `"direct"` + A refusal from the model. - - `Program object { caller_id, type }` + - `refusal: string` - - `caller_id: string` + The refusal explanation from the model. - The call ID of the program item that produced this tool call. + - `type: "refusal"` - - `type: "program"` + The type of the refusal. Always `refusal`. - The caller type. Always `program`. + - `"refusal"` - - `"program"` + - `role: "assistant"` - - `created_by: optional string` + The role of the output message. Always `assistant`. - The identifier of the actor that created the item. + - `"assistant"` - - `parallel_tool_calls: boolean` + - `status: "in_progress" or "completed" or "incomplete"` - Whether to allow the model to run tool calls in parallel. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `temperature: number` + - `"in_progress"` - 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. + - `"completed"` - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + - `"incomplete"` + + - `type: "message"` + + The type of the output message. Always `message`. + + - `"message"` + + - `agent: optional object { agent_name }` - 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 agent that produced this item. - - `BetaToolChoiceOptions = "none" or "auto" or "required"` + - `agent_name: string` - Controls which (if any) tool is called by the model. + The canonical name of the agent that produced this item. - `none` means the model will not call any tool and instead generates a message. + - `phase: optional "commentary" or "final_answer"` - `auto` means the model can pick between generating a message or calling one or - more tools. + 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. - `required` means the model must call one or more tools. + - `"commentary"` - - `"none"` + - `"final_answer"` - - `"auto"` + - `FileSearchCall object { id, queries, status, 3 more }` - - `"required"` + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - - `BetaToolChoiceAllowed object { mode, tools, type }` + - `id: string` - Constrains the tools available to the model to a pre-defined set. + The unique ID of the file search tool call. - - `mode: "auto" or "required"` + - `queries: array of string` - Constrains the tools available to the model to a pre-defined set. + The queries used to search for files. - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `status: "in_progress" or "searching" or "completed" or 2 more` - `required` requires the model to call one or more of the allowed tools. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `"auto"` + - `"in_progress"` - - `"required"` + - `"searching"` - - `tools: array of map[unknown]` + - `"completed"` - A list of tool definitions that the model should be allowed to call. + - `"incomplete"` - For the Responses API, the list of tool definitions might look like: + - `"failed"` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `type: "file_search_call"` - - `type: "allowed_tools"` + The type of the file search tool call. Always `file_search_call`. - Allowed tool configuration type. Always `allowed_tools`. + - `"file_search_call"` - - `"allowed_tools"` + - `agent: optional object { agent_name }` - - `BetaToolChoiceTypes object { type }` + The agent that produced this item. - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](/docs/guides/tools). + - `agent_name: string` - - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + The canonical name of the agent that produced this item. - The type of hosted tool the model should to use. Learn more about - [built-in tools](/docs/guides/tools). + - `results: optional array of object { attributes, file_id, filename, 2 more }` - Allowed values are: + The results of the file search tool call. - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `attributes: optional map[string or number or boolean]` - - `"file_search"` + 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. - - `"web_search_preview"` + - `string` - - `"computer"` + - `number` - - `"computer_use_preview"` + - `boolean` - - `"computer_use"` + - `file_id: optional string` - - `"web_search_preview_2025_03_11"` + The unique ID of the file. - - `"image_generation"` + - `filename: optional string` - - `"code_interpreter"` + The name of the file. - - `BetaToolChoiceFunction object { name, type }` + - `score: optional number` - Use this option to force the model to call a specific function. + The relevance score of the file - a value between 0 and 1. - - `name: string` + - `text: optional string` - The name of the function to call. + The text that was retrieved from the file. - - `type: "function"` + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - For function calling, the type is always `function`. + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - - `"function"` + - `id: string` - - `BetaToolChoiceMcp object { server_label, type, name }` + The unique ID of the computer call. - Use this option to force the model to call a specific tool on a remote MCP server. + - `call_id: string` - - `server_label: string` + An identifier used when responding to the tool call with output. - The label of the MCP server to use. + - `pending_safety_checks: array of object { id, code, message }` - - `type: "mcp"` + The pending safety checks for the computer call. - For MCP tools, the type is always `mcp`. + - `id: string` - - `"mcp"` + The ID of the pending safety check. - - `name: optional string` + - `code: optional string` - The name of the tool to call on the server. + The type of the pending safety check. - - `BetaToolChoiceCustom object { name, type }` + - `message: optional string` - Use this option to force the model to call a specific custom tool. + Details about the pending safety check. - - `name: string` + - `status: "in_progress" or "completed" or "incomplete"` - The name of the custom tool to call. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `type: "custom"` + - `"in_progress"` - For custom tool calling, the type is always `custom`. + - `"completed"` - - `"custom"` + - `"incomplete"` - - `BetaSpecificProgrammaticToolCallingParam object { type }` + - `type: "computer_call"` - - `type: "programmatic_tool_calling"` + The type of the computer call. Always `computer_call`. - The tool to call. Always `programmatic_tool_calling`. + - `"computer_call"` - - `"programmatic_tool_calling"` + - `action: optional BetaComputerAction` - - `BetaToolChoiceApplyPatch object { type }` + A click action. - Forces the model to call the apply_patch tool when executing a tool call. + - `Click object { button, type, x, 2 more }` - - `type: "apply_patch"` + A click action. - The tool to call. Always `apply_patch`. + - `button: "left" or "right" or "wheel" or 2 more` - - `"apply_patch"` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `BetaToolChoiceShell object { type }` + - `"left"` - Forces the model to call the shell tool when a tool call is required. + - `"right"` - - `type: "shell"` + - `"wheel"` - The tool to call. Always `shell`. + - `"back"` - - `"shell"` + - `"forward"` - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + - `type: "click"` - 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. + Specifies the event type. For a click action, this property is always `click`. - We support the following categories of tools: + - `"click"` - - **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. + - `x: number` - - `Function object { name, parameters, strict, 5 more }` + The x-coordinate where the click occurred. - 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). + - `y: number` - - `name: string` + The y-coordinate where the click occurred. - The name of the function to call. + - `keys: optional array of string` - - `parameters: map[unknown]` + The keys being held while clicking. - A JSON schema object describing the parameters of the function. + - `DoubleClick object { keys, type, x, y }` - - `strict: boolean` + A double click action. - Whether strict parameter validation is enforced for this function tool. + - `keys: array of string` - - `type: "function"` + The keys being held while double-clicking. - The type of the function tool. Always `function`. + - `type: "double_click"` - - `"function"` + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"double_click"` - The tool invocation context(s). + - `x: number` - - `"direct"` + The x-coordinate where the double click occurred. - - `"programmatic"` + - `y: number` - - `defer_loading: optional boolean` + The y-coordinate where the double click occurred. - Whether this function is deferred and loaded via tool search. + - `Drag object { path, type, keys }` - - `description: optional string` + A drag action. - A description of the function. Used by the model to determine whether or not to call the function. + - `path: array of object { x, y }` - - `output_schema: optional map[unknown]` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - A JSON schema object describing the JSON value encoded in string outputs for this function. + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `x: number` - 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 x-coordinate. - - `type: "file_search"` + - `y: number` - The type of the file search tool. Always `file_search`. + The y-coordinate. - - `"file_search"` + - `type: "drag"` - - `vector_store_ids: array of string` + Specifies the event type. For a drag action, this property is always set to `drag`. - The IDs of the vector stores to search. + - `"drag"` - - `filters: optional object { key, type, value } or object { filters, type }` + - `keys: optional array of string` - A filter to apply. + The keys being held while dragging the mouse. - - `ComparisonFilter object { key, type, value }` + - `Keypress object { keys, type }` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + A collection of keypresses the model would like to perform. - - `key: string` + - `keys: array of string` - The key to compare against the value. + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `type: "eq" or "ne" or "gt" or 5 more` + - `type: "keypress"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + - `"keypress"` - - `"eq"` + - `Move object { type, x, y, keys }` - - `"ne"` + A mouse move action. - - `"gt"` + - `type: "move"` - - `"gte"` + Specifies the event type. For a move action, this property is always set to `move`. - - `"lt"` + - `"move"` - - `"lte"` + - `x: number` - - `"in"` + The x-coordinate to move to. - - `"nin"` + - `y: number` - - `value: string or number or boolean or array of string or number` + The y-coordinate to move to. - The value to compare against the attribute key; supports string, number, or boolean types. + - `keys: optional array of string` - - `string` + The keys being held while moving the mouse. - - `number` + - `Screenshot object { type }` - - `boolean` + A screenshot action. - - `array of string or number` + - `type: "screenshot"` - - `string` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `number` + - `"screenshot"` - - `CompoundFilter object { filters, type }` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - Combine multiple filters using `and` or `or`. + A scroll action. - - `filters: array of object { key, type, value } or unknown` + - `scroll_x: number` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + The horizontal scroll distance. - - `ComparisonFilter object { key, type, value }` + - `scroll_y: number` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The vertical scroll distance. - - `key: string` + - `type: "scroll"` - The key to compare against the value. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `type: "eq" or "ne" or "gt" or 5 more` + - `"scroll"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `x: number` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + The x-coordinate where the scroll occurred. - - `"eq"` + - `y: number` - - `"ne"` + The y-coordinate where the scroll occurred. - - `"gt"` + - `keys: optional array of string` - - `"gte"` + The keys being held while scrolling. - - `"lt"` + - `Type object { text, type }` - - `"lte"` + An action to type in text. - - `"in"` + - `text: string` - - `"nin"` + The text to type. - - `value: string or number or boolean or array of string or number` + - `type: "type"` - The value to compare against the attribute key; supports string, number, or boolean types. + Specifies the event type. For a type action, this property is always set to `type`. - - `string` + - `"type"` - - `number` + - `Wait object { type }` - - `boolean` + A wait action. - - `array of string or number` + - `type: "wait"` - - `string` + Specifies the event type. For a wait action, this property is always set to `wait`. - - `number` + - `"wait"` - - `unknown` + - `actions: optional BetaComputerActionList` - - `type: "and" or "or"` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - Type of operation: `and` or `or`. + - `Click object { button, type, x, 2 more }` - - `"and"` + A click action. - - `"or"` + - `DoubleClick object { keys, type, x, y }` - - `max_num_results: optional number` + A double click action. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `Drag object { path, type, keys }` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + A drag action. - Ranking options for search. + - `Keypress object { keys, type }` - - `hybrid_search: optional object { embedding_weight, text_weight }` + A collection of keypresses the model would like to perform. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `Move object { type, x, y, keys }` - - `embedding_weight: number` + A mouse move action. - The weight of the embedding in the reciprocal ranking fusion. + - `Screenshot object { type }` - - `text_weight: number` + A screenshot action. - The weight of the text in the reciprocal ranking fusion. + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `ranker: optional "auto" or "default-2024-11-15"` + A scroll action. - The ranker to use for the file search. + - `Type object { text, type }` - - `"auto"` + An action to type in text. - - `"default-2024-11-15"` + - `Wait object { type }` - - `score_threshold: optional number` + A wait action. - 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. + - `agent: optional object { agent_name }` - - `Computer object { type }` + The agent that produced this item. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `agent_name: string` - - `type: "computer"` + The canonical name of the agent that produced this item. - The type of the computer tool. Always `computer`. + - `ComputerCallOutput object { call_id, output, type, 4 more }` - - `"computer"` + The output of a computer tool call. - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `call_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 computer tool call that produced the output. - - `display_height: number` + - `output: BetaResponseComputerToolCallOutputScreenshot` - The height of the computer display. + A computer screenshot image used with the computer use tool. - - `display_width: number` + - `type: "computer_screenshot"` - The width of the computer display. + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `environment: "windows" or "mac" or "linux" or 2 more` + - `"computer_screenshot"` - The type of computer environment to control. + - `file_id: optional string` - - `"windows"` + The identifier of an uploaded file that contains the screenshot. - - `"mac"` + - `image_url: optional string` - - `"linux"` + The URL of the screenshot image. - - `"ubuntu"` + - `type: "computer_call_output"` - - `"browser"` + The type of the computer tool call output. Always `computer_call_output`. - - `type: "computer_use_preview"` + - `"computer_call_output"` - The type of the computer use tool. Always `computer_use_preview`. + - `id: optional string` - - `"computer_use_preview"` + The ID of the computer tool call output. - - `WebSearch object { type, filters, search_context_size, user_location }` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + The safety checks reported by the API that have been acknowledged by the developer. - - `type: "web_search" or "web_search_2025_08_26"` + - `id: string` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + The ID of the pending safety check. - - `"web_search"` + - `code: optional string` - - `"web_search_2025_08_26"` + The type of the pending safety check. - - `filters: optional object { allowed_domains }` + - `message: optional string` - Filters for the search. + Details about the pending safety check. - - `allowed_domains: optional array of string` + - `agent: optional object { agent_name }` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + The agent that produced this item. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `agent_name: string` - - `search_context_size: optional "low" or "medium" or "high"` + The canonical name of the agent that produced this 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. + - `status: optional "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. + - `WebSearchCall object { id, action, status, 2 more }` - - `city: optional string` + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - Free text input for the city of the user, e.g. `San Francisco`. + - `id: string` - - `country: optional string` + The unique ID of the web search tool call. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `region: optional string` + An object describing the specific action taken in this web search call. + Includes details on how the model used the web (search, open_page, find_in_page). - Free text input for the region of the user, e.g. `California`. + - `Search object { type, queries, query, sources }` - - `timezone: optional string` + Action type "search" - Performs a web search query. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `type: "search"` - - `type: optional "approximate"` + The action type. - The type of location approximation. Always `approximate`. + - `"search"` - - `"approximate"` + - `queries: optional array of string` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + The search queries. - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + - `query: optional string` - - `server_label: string` + The search query. - A label for this MCP server, used to identify it in tool calls. + - `sources: optional array of object { type, url }` - - `type: "mcp"` + The sources used in the search. - The type of the MCP tool. Always `mcp`. + - `type: "url"` - - `"mcp"` + The type of source. Always `url`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"url"` - The tool invocation context(s). + - `url: string` - - `"direct"` + The URL of the source. - - `"programmatic"` + - `OpenPage object { type, url }` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + Action type "open_page" - Opens a specific URL from search results. - List of allowed tool names or a filter object. + - `type: "open_page"` - - `McpAllowedTools = array of string` + The action type. - A string array of allowed tool names + - `"open_page"` - - `McpToolFilter object { read_only, tool_names }` + - `url: optional string` - A filter object to specify which tools are allowed. + The URL opened by the model. - - `read_only: optional boolean` + - `FindInPage object { pattern, type, url }` - 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. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `tool_names: optional array of string` + - `pattern: string` - List of allowed tool names. + The pattern or text to search for within the page. - - `authorization: optional string` + - `type: "find_in_page"` - 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 action type. - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `"find_in_page"` - 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). + - `url: string` - Currently supported `connector_id` values are: + The URL of the page searched for the pattern. - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `"connector_dropbox"` + The status of the web search tool call. - - `"connector_gmail"` + - `"in_progress"` - - `"connector_googlecalendar"` + - `"searching"` - - `"connector_googledrive"` + - `"completed"` - - `"connector_microsoftteams"` + - `"failed"` - - `"connector_outlookcalendar"` + - `type: "web_search_call"` - - `"connector_outlookemail"` + The type of the web search tool call. Always `web_search_call`. - - `"connector_sharepoint"` + - `"web_search_call"` - - `defer_loading: optional boolean` + - `agent: optional object { agent_name }` - Whether this MCP tool is deferred and discovered via tool search. + The agent that produced this item. - - `headers: optional map[string]` + - `agent_name: string` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The canonical name of the agent that produced this item. - - `require_approval: optional object { always, never } or "always" or "never"` + - `FunctionCall object { arguments, call_id, name, 6 more }` - Specify which of the MCP server's tools require approval. + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `McpToolApprovalFilter object { always, never }` + - `arguments: 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. + A JSON string of the arguments to pass to the function. - - `always: optional object { read_only, tool_names }` + - `call_id: string` - A filter object to specify which tools are allowed. + The unique ID of the function tool call generated by the model. - - `read_only: optional boolean` + - `name: string` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The name of the function to run. - - `tool_names: optional array of string` + - `type: "function_call"` - List of allowed tool names. + The type of the function tool call. Always `function_call`. - - `never: optional object { read_only, tool_names }` + - `"function_call"` - A filter object to specify which tools are allowed. + - `id: optional string` - - `read_only: optional boolean` + The unique ID of the function 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. + - `agent: optional object { agent_name }` - - `tool_names: optional array of string` + The agent that produced this item. - List of allowed tool names. + - `agent_name: string` - - `McpToolApprovalSetting = "always" or "never"` + The canonical name of the agent that produced this item. - 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: optional object { type } or object { caller_id, type }` - - `"always"` + The execution context that produced this tool call. - - `"never"` + - `Direct object { type }` - - `server_description: optional string` + - `type: "direct"` - Optional description of the MCP server, used to provide more context. + - `"direct"` - - `server_url: optional string` + - `Program object { caller_id, type }` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `caller_id: string` - - `tunnel_id: optional string` + The call ID of the program item that produced 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. + - `type: "program"` - - `CodeInterpreter object { container, type, allowed_callers }` + - `"program"` - A tool that runs Python code to help generate a response to a prompt. + - `namespace: optional string` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + The namespace of the function to run. - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `string` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The container ID. + - `"in_progress"` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `"completed"` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `"incomplete"` - - `type: "auto"` + - `FunctionCallOutput object { call_id, output, type, 4 more }` - Always `auto`. + The output of a function tool call. - - `"auto"` + - `call_id: string` - - `file_ids: optional array of string` + The unique ID of the function tool call generated by the model. - An optional list of uploaded files to make available to your code. + - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + Text, image, or file output of the function tool call. - The memory limit for the code interpreter container. + - `string` - - `"1g"` + A JSON string of the output of the function tool call. - - `"4g"` + - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - - `"16g"` + An array of content outputs (text, image, file) for the function tool call. - - `"64g"` + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + A text input to the model. - Network access policy for the container. + - `text: string` - - `BetaContainerNetworkPolicyDisabled object { type }` + The text input to the model. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `type: "input_text"` - - `type: "code_interpreter"` + The type of the input item. Always `input_text`. - The type of the code interpreter tool. Always `code_interpreter`. + - `"input_text"` - - `"code_interpreter"` + - `prompt_cache_breakpoint: optional object { mode }` - - `allowed_callers: optional array of "direct" or "programmatic"` + 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 tool invocation context(s). + - `mode: "explicit"` - - `"direct"` + The breakpoint mode. Always `explicit`. - - `"programmatic"` + - `"explicit"` - - `ProgrammaticToolCalling object { type }` + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - - `type: "programmatic_tool_calling"` + An image input to the model. Learn about [image inputs](/docs/guides/vision) - The type of the tool. Always `programmatic_tool_calling`. + - `type: "input_image"` - - `"programmatic_tool_calling"` + The type of the input item. Always `input_image`. - - `ImageGeneration object { type, action, background, 9 more }` + - `"input_image"` - A tool that generates images using the GPT image models. + - `detail: optional "low" or "high" or "auto" or "original"` - - `type: "image_generation"` + 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 the image generation tool. Always `image_generation`. + - `"low"` - - `"image_generation"` + - `"high"` - - `action: optional "generate" or "edit" or "auto"` + - `"auto"` - Whether to generate a new image or edit an existing image. Default: `auto`. + - `"original"` - - `"generate"` + - `file_id: optional string` - - `"edit"` + The ID of the file to be sent to the model. - - `"auto"` + - `image_url: optional string` - - `background: optional "transparent" or "opaque" or "auto"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + - `prompt_cache_breakpoint: optional object { mode }` - - `"transparent"` + 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. - - `"opaque"` + - `mode: "explicit"` - - `"auto"` + The breakpoint mode. Always `explicit`. - - `input_fidelity: optional "high" or "low"` + - `"explicit"` - 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`. + - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` - - `"high"` + A file input to the model. - - `"low"` + - `type: "input_file"` - - `input_image_mask: optional object { file_id, image_url }` + The type of the input item. Always `input_file`. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `"input_file"` - - `file_id: optional string` + - `detail: optional "auto" or "low" or "high"` - File ID for the mask 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`. - - `image_url: optional string` + - `"auto"` - Base64-encoded mask image. + - `"low"` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"high"` - The image generation model to use. Default: `gpt-image-1`. + - `file_data: optional string` - - `string` + The base64-encoded data of the file to be sent to the model. - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `file_id: optional string` - The image generation model to use. Default: `gpt-image-1`. + The ID of the file to be sent to the model. - - `"gpt-image-1"` + - `file_url: optional string` - - `"gpt-image-1-mini"` + The URL of the file to be sent to the model. - - `"gpt-image-1.5"` + - `filename: optional string` - - `moderation: optional "auto" or "low"` + The name of the file to be sent to the model. - Moderation level for the generated image. Default: `auto`. + - `prompt_cache_breakpoint: optional object { mode }` - - `"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"` - - `output_compression: optional number` + The breakpoint mode. Always `explicit`. - Compression level for the output image. Default: 100. + - `"explicit"` - - `output_format: optional "png" or "webp" or "jpeg"` + - `type: "function_call_output"` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + The type of the function tool call output. Always `function_call_output`. - - `"png"` + - `"function_call_output"` - - `"webp"` + - `id: optional string` - - `"jpeg"` + The unique ID of the function tool call output. Populated when this item is returned via API. - - `partial_images: optional number` + - `agent: optional object { agent_name }` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The agent that produced this item. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `agent_name: string` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The canonical name of the agent that produced this item. - - `"low"` + - `caller: optional object { type } or object { caller_id, type }` - - `"medium"` + The execution context that produced this tool call. - - `"high"` + - `Direct object { type }` - - `"auto"` + - `type: "direct"` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The caller type. Always `direct`. - 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`. + - `"direct"` - - `string` + - `Program object { caller_id, type }` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `caller_id: string` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + The call ID of the program item that produced this tool call. - - `"1024x1024"` + - `type: "program"` - - `"1024x1536"` + The caller type. Always `program`. - - `"1536x1024"` + - `"program"` - - `"auto"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `LocalShell object { type }` + 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 a local environment. + - `"in_progress"` - - `type: "local_shell"` + - `"completed"` - The type of the local shell tool. Always `local_shell`. + - `"incomplete"` - - `"local_shell"` + - `AgentMessage object { author, content, recipient, 3 more }` - - `Shell object { type, allowed_callers, environment }` + A message routed between agents. - A tool that allows the model to execute shell commands. + - `author: string` - - `type: "shell"` + The sending agent identity. - The type of the shell tool. Always `shell`. + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - - `"shell"` + Plaintext, image, or encrypted content sent between agents. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - The tool invocation context(s). + A text input to the model. - - `"direct"` + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - - `"programmatic"` + An image input to the model. Learn about [image inputs](/docs/guides/vision) - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `EncryptedContent object { encrypted_content, type }` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `BetaLocalEnvironment object { type, skills }` + - `encrypted_content: string` - - `BetaContainerReference object { container_id, type }` + Opaque encrypted content. - - `Custom object { name, type, allowed_callers, 3 more }` + - `type: "encrypted_content"` - 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 input item. Always `encrypted_content`. - - `name: string` + - `"encrypted_content"` - The name of the custom tool, used to identify it in tool calls. + - `recipient: string` - - `type: "custom"` + The destination agent identity. - The type of the custom tool. Always `custom`. + - `type: "agent_message"` - - `"custom"` + The item type. Always `agent_message`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"agent_message"` - The tool invocation context(s). + - `id: optional string` - - `"direct"` + The unique ID of this agent message item. - - `"programmatic"` + - `agent: optional object { agent_name }` - - `defer_loading: optional boolean` + The agent that produced this item. - Whether this tool should be deferred and discovered via tool search. + - `agent_name: string` - - `description: optional string` + The canonical name of the agent that produced this item. - Optional description of the custom tool, used to provide more context. + - `MultiAgentCall object { action, arguments, call_id, 3 more }` - - `format: optional object { type } or object { definition, syntax, type }` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - The input format for the custom tool. Default is unconstrained text. + The multi-agent action that was executed. - - `Text object { type }` + - `"spawn_agent"` - Unconstrained free-form text. + - `"interrupt_agent"` - - `type: "text"` + - `"list_agents"` - Unconstrained text format. Always `text`. + - `"send_message"` - - `"text"` + - `"followup_task"` - - `Grammar object { definition, syntax, type }` + - `"wait_agent"` - A grammar defined by the user. + - `arguments: string` - - `definition: string` + The action arguments as a JSON string. - The grammar definition. + - `call_id: string` - - `syntax: "lark" or "regex"` + The unique ID linking this call to its output. - The syntax of the grammar definition. One of `lark` or `regex`. + - `type: "multi_agent_call"` - - `"lark"` + The item type. Always `multi_agent_call`. - - `"regex"` + - `"multi_agent_call"` - - `type: "grammar"` + - `id: optional string` - Grammar format. Always `grammar`. + The unique ID of this multi-agent call. - - `"grammar"` + - `agent: optional object { agent_name }` - - `Namespace object { description, name, tools, type }` + The agent that produced this item. - Groups function/custom tools under a shared namespace. + - `agent_name: string` - - `description: string` + The canonical name of the agent that produced this item. - A description of the namespace shown to the model. + - `MultiAgentCallOutput object { action, call_id, output, 3 more }` - - `name: string` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - The namespace name used in tool calls (for example, `crm`). + The multi-agent action that produced this result. - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `"spawn_agent"` - The function/custom tools available inside this namespace. + - `"interrupt_agent"` - - `Function object { name, type, allowed_callers, 5 more }` + - `"list_agents"` - - `name: string` + - `"send_message"` - - `type: "function"` + - `"followup_task"` - - `"function"` + - `"wait_agent"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `call_id: string` - The tool invocation context(s). + The unique ID of the multi-agent call. - - `"direct"` + - `output: array of object { text, type, annotations }` - - `"programmatic"` + Text output returned by the multi-agent action. - - `defer_loading: optional boolean` + - `text: string` - Whether this function should be deferred and discovered via tool search. + The text content. - - `description: optional string` + - `type: "output_text"` - - `output_schema: optional map[unknown]` + The content type. Always `output_text`. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `"output_text"` - - `parameters: optional unknown` + - `annotations: optional 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 }` - - `strict: optional boolean` + Citations associated with the text content. - 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. + - `FileCitation object { file_id, filename, index, type }` - - `Custom object { name, type, allowed_callers, 3 more }` + - `file_id: string` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + The ID of the file. - - `name: string` + - `filename: string` - The name of the custom tool, used to identify it in tool calls. + The filename of the file cited. - - `type: "custom"` + - `index: number` - The type of the custom tool. Always `custom`. + The index of the file in the list of files. - - `"custom"` + - `type: "file_citation"` - - `allowed_callers: optional array of "direct" or "programmatic"` + The citation type. Always `file_citation`. - The tool invocation context(s). + - `"file_citation"` - - `"direct"` + - `URLCitation object { end_index, start_index, title, 2 more }` - - `"programmatic"` + - `end_index: number` - - `defer_loading: optional boolean` + The index of the last character of the citation in the message. - Whether this tool should be deferred and discovered via tool search. + - `start_index: number` - - `description: optional string` + The index of the first character of the citation in the message. - Optional description of the custom tool, used to provide more context. + - `title: string` - - `format: optional object { type } or object { definition, syntax, type }` + The title of the cited resource. - The input format for the custom tool. Default is unconstrained text. + - `type: "url_citation"` - - `Text object { type }` + The citation type. Always `url_citation`. - Unconstrained free-form text. + - `"url_citation"` - - `type: "text"` + - `url: string` - Unconstrained text format. Always `text`. + The URL of the cited resource. - - `"text"` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - - `Grammar object { definition, syntax, type }` + - `container_id: string` - A grammar defined by the user. + The ID of the container. - - `definition: string` + - `end_index: number` - The grammar definition. + The index of the last character of the citation in the message. - - `syntax: "lark" or "regex"` + - `file_id: string` - The syntax of the grammar definition. One of `lark` or `regex`. + The ID of the container file. - - `"lark"` + - `filename: string` - - `"regex"` + The filename of the container file cited. - - `type: "grammar"` + - `start_index: number` - Grammar format. Always `grammar`. + The index of the first character of the citation in the message. - - `"grammar"` + - `type: "container_file_citation"` - - `type: "namespace"` + The citation type. Always `container_file_citation`. - The type of the tool. Always `namespace`. + - `"container_file_citation"` - - `"namespace"` + - `type: "multi_agent_call_output"` - - `ToolSearch object { type, description, execution, parameters }` + The item type. Always `multi_agent_call_output`. - Hosted or BYOT tool search configuration for deferred tools. + - `"multi_agent_call_output"` - - `type: "tool_search"` + - `id: optional string` - The type of the tool. Always `tool_search`. + The unique ID of this multi-agent call output. - - `"tool_search"` + - `agent: optional object { agent_name }` - - `description: optional string` + The agent that produced this item. - Description shown to the model for a client-executed tool search tool. + - `agent_name: string` - - `execution: optional "server" or "client"` + The canonical name of the agent that produced this item. - Whether tool search is executed by the server or by the client. + - `ToolSearchCall object { arguments, type, id, 4 more }` - - `"server"` + - `arguments: unknown` - - `"client"` + The arguments supplied to the tool search call. - - `parameters: optional unknown` + - `type: "tool_search_call"` - Parameter schema for a client-executed tool search tool. + The item type. Always `tool_search_call`. - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `"tool_search_call"` - 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). + - `id: optional string` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + The unique ID of this tool search call. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `agent: optional object { agent_name }` - - `"web_search_preview"` + The agent that produced this item. - - `"web_search_preview_2025_03_11"` + - `agent_name: string` - - `search_content_types: optional array of "text" or "image"` + The canonical name of the agent that produced this item. - - `"text"` + - `call_id: optional string` - - `"image"` + The unique ID of the tool search call generated by the model. - - `search_context_size: optional "low" or "medium" or "high"` + - `execution: optional "server" or "client"` - 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. + Whether tool search was executed by the server or by the client. - - `"low"` + - `"server"` - - `"medium"` + - `"client"` - - `"high"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `user_location: optional object { type, city, country, 2 more }` + The status of the tool search call. - The user's location. + - `"in_progress"` - - `type: "approximate"` + - `"completed"` - The type of location approximation. Always `approximate`. + - `"incomplete"` - - `"approximate"` + - `ToolSearchOutput object { tools, type, id, 4 more }` - - `city: optional string` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - Free text input for the city of the user, e.g. `San Francisco`. + The loaded tool definitions returned by the tool search output. - - `country: optional string` + - `Function object { name, parameters, strict, 5 more }` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + 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). - - `region: optional string` + - `name: string` - Free text input for the region of the user, e.g. `California`. + The name of the function to call. - - `timezone: optional string` + - `parameters: map[unknown]` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + A JSON schema object describing the parameters of the function. - - `ApplyPatch object { type, allowed_callers }` + - `strict: boolean` - Allows the assistant to create, delete, or update files using unified diffs. + Whether strict parameter validation is enforced for this function tool. - - `type: "apply_patch"` + - `type: "function"` - The type of the tool. Always `apply_patch`. + The type of the function tool. Always `function`. - - `"apply_patch"` + - `"function"` - `allowed_callers: optional array of "direct" or "programmatic"` @@ -168924,279 +168621,261 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"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` + - `defer_loading: optional boolean` - Whether to run the model response in the background. - [Learn more](/docs/guides/background). + Whether this function is deferred and loaded via tool search. - - `completed_at: optional number` + - `description: optional string` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + A description of the function. Used by the model to determine whether or not to call the function. - - `conversation: optional object { id }` + - `output_schema: optional map[unknown]` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `id: string` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - The unique ID of the conversation that this response was associated with. + 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). - - `max_output_tokens: optional number` + - `type: "file_search"` - 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 type of the file search tool. Always `file_search`. - - `max_tool_calls: optional number` + - `"file_search"` - 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. + - `vector_store_ids: array of string` - - `moderation: optional object { input, output }` + The IDs of the vector stores to search. - Moderation results for the response input and output, if moderated completions were requested. + - `filters: optional object { key, type, value } or object { filters, type }` - - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + A filter to apply. - Moderation for the response input. + - `ComparisonFilter object { key, type, value }` - - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - A moderation result produced for the response input or output. + - `key: string` - - `categories: map[boolean]` + The key to compare against the value. - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + - `type: "eq" or "ne" or "gt" or 5 more` - - `category_applied_input_types: map[array of "text" or "image"]` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - Which modalities of input are reflected by the score for each category. + - `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 - - `"text"` + - `"eq"` - - `"image"` + - `"ne"` - - `category_scores: map[number]` + - `"gt"` - A dictionary of moderation categories to scores. + - `"gte"` - - `flagged: boolean` + - `"lt"` - A boolean indicating whether the content was flagged by any category. + - `"lte"` - - `model: string` + - `"in"` - The moderation model that produced this result. + - `"nin"` - - `type: "moderation_result"` + - `value: string or number or boolean or array of string or number` - The object type, which was always `moderation_result` for successful moderation results. + The value to compare against the attribute key; supports string, number, or boolean types. - - `"moderation_result"` + - `string` - - `Error object { code, message, type }` + - `number` - An error produced while attempting moderation for the response input or output. + - `boolean` - - `code: string` + - `array of string or number` - The error code. + - `string` - - `message: string` + - `number` - The error message. + - `CompoundFilter object { filters, type }` - - `type: "error"` + Combine multiple filters using `and` or `or`. - The object type, which was always `error` for moderation failures. + - `filters: array of object { key, type, value } or unknown` - - `"error"` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + - `ComparisonFilter object { key, type, value }` - Moderation for the response output. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + - `key: string` - A moderation result produced for the response input or output. + The key to compare against the value. - - `categories: map[boolean]` + - `type: "eq" or "ne" or "gt" or 5 more` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `category_applied_input_types: map[array of "text" or "image"]` + - `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 - Which modalities of input are reflected by the score for each category. + - `"eq"` - - `"text"` + - `"ne"` - - `"image"` + - `"gt"` - - `category_scores: map[number]` + - `"gte"` - A dictionary of moderation categories to scores. + - `"lt"` - - `flagged: boolean` + - `"lte"` - A boolean indicating whether the content was flagged by any category. + - `"in"` - - `model: string` + - `"nin"` - The moderation model that produced this result. + - `value: string or number or boolean or array of string or number` - - `type: "moderation_result"` + The value to compare against the attribute key; supports string, number, or boolean types. - The object type, which was always `moderation_result` for successful moderation results. + - `string` - - `"moderation_result"` + - `number` - - `Error object { code, message, type }` + - `boolean` - An error produced while attempting moderation for the response input or output. + - `array of string or number` - - `code: string` + - `string` - The error code. + - `number` - - `message: string` + - `unknown` - The error message. + - `type: "and" or "or"` - - `type: "error"` + Type of operation: `and` or `or`. - The object type, which was always `error` for moderation failures. + - `"and"` - - `"error"` + - `"or"` - - `output_text: optional string` + - `max_num_results: optional number` - 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 maximum number of results to return. This number should be between 1 and 50 inclusive. - - `previous_response_id: optional string` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - 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`. + Ranking options for search. - - `prompt: optional BetaResponsePrompt` + - `hybrid_search: optional object { embedding_weight, text_weight }` - Reference to a prompt template and its variables. - [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). + 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 identifier of the prompt template to use. + The weight of the embedding in the reciprocal ranking fusion. - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + - `text_weight: number` - 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 weight of the text in the reciprocal ranking fusion. - - `string` + - `ranker: optional "auto" or "default-2024-11-15"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + The ranker to use for the file search. - A text input to the model. + - `"auto"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `"default-2024-11-15"` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `score_threshold: optional number` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - A file input to the model. + - `Computer object { type }` - - `version: optional string` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Optional version of the prompt template. + - `type: "computer"` - - `prompt_cache_key: optional string` + The type of the computer tool. Always `computer`. - 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). + - `"computer"` - - `prompt_cache_options: optional object { mode, ttl }` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `mode: "implicit" or "explicit"` + - `display_height: number` - Whether implicit prompt-cache breakpoints were enabled. + The height of the computer display. - - `"implicit"` + - `display_width: number` - - `"explicit"` + The width of the computer display. - - `ttl: "30m"` + - `environment: "windows" or "mac" or "linux" or 2 more` - The minimum lifetime applied to each cache breakpoint. + The type of computer environment to control. - - `"30m"` + - `"windows"` - - `prompt_cache_retention: optional "in_memory" or "24h"` + - `"mac"` - Deprecated. Use `prompt_cache_options.ttl` instead. + - `"linux"` - 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. + - `"ubuntu"` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `"browser"` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `type: "computer_use_preview"` - - `"in_memory"` + The type of the computer use tool. Always `computer_use_preview`. - - `"24h"` + - `"computer_use_preview"` - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + - `WebSearch object { type, filters, search_context_size, user_location }` - **gpt-5 and o-series models only** + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `type: "web_search" or "web_search_2025_08_26"` - - `context: optional "auto" or "current_turn" or "all_turns"` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - 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`. + - `"web_search"` - When returned on a response, this is the effective reasoning context mode - used for the response. + - `"web_search_2025_08_26"` - - `"auto"` + - `filters: optional object { allowed_domains }` - - `"current_turn"` + Filters for the search. - - `"all_turns"` + - `allowed_domains: optional array of string` - - `effort: optional "none" or "minimal" or "low" or 4 more` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - 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. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `"none"` + - `search_context_size: optional "low" or "medium" or "high"` - - `"minimal"` + 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"` @@ -169204,2567 +168883,2550 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"high"` - - `"xhigh"` - - - `"max"` - - - `generate_summary: optional "auto" or "concise" or "detailed"` + - `user_location: optional object { city, country, region, 2 more }` - **Deprecated:** use `summary` instead. + The approximate location of the user. - 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`. + - `city: optional string` - - `"auto"` + Free text input for the city of the user, e.g. `San Francisco`. - - `"concise"` + - `country: optional string` - - `"detailed"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `mode: optional string or "standard" or "pro"` + - `region: optional string` - Controls the reasoning execution mode for the request. + Free text input for the region of the user, e.g. `California`. - When returned on a response, this is the effective execution mode. + - `timezone: optional string` - - `string` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"standard" or "pro"` + - `type: optional "approximate"` - Controls the reasoning execution mode for the request. + The type of location approximation. Always `approximate`. - When returned on a response, this is the effective execution mode. + - `"approximate"` - - `"standard"` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `"pro"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `summary: optional "auto" or "concise" or "detailed"` + - `server_label: 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`. + A label for this MCP server, used to identify it in tool calls. - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `type: "mcp"` - - `"auto"` + The type of the MCP tool. Always `mcp`. - - `"concise"` + - `"mcp"` - - `"detailed"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `safety_identifier: optional string` + The tool invocation context(s). - 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). + - `"direct"` - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + - `"programmatic"` - Specifies the processing type used for serving the request. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - 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'. + List of allowed tool names or a filter object. - 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. + - `McpAllowedTools = array of string` - - `"auto"` + A string array of allowed tool names - - `"default"` + - `McpToolFilter object { read_only, tool_names }` - - `"flex"` + A filter object to specify which tools are allowed. - - `"scale"` + - `read_only: optional boolean` - - `"priority"` + 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 BetaResponseStatus` + - `tool_names: optional array of string` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + List of allowed tool names. - - `"completed"` + - `authorization: optional string` - - `"failed"` + 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. - - `"in_progress"` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `"cancelled"` + 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). - - `"queued"` + 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` - - `text: optional BetaResponseTextConfig` + - `"connector_dropbox"` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `"connector_gmail"` - - [Text inputs and outputs](/docs/guides/text) - - [Structured Outputs](/docs/guides/structured-outputs) + - `"connector_googlecalendar"` - - `format: optional BetaResponseFormatTextConfig` + - `"connector_googledrive"` - An object specifying the format that the model must output. + - `"connector_microsoftteams"` - 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). + - `"connector_outlookcalendar"` - The default format is `{ "type": "text" }` with no additional options. + - `"connector_outlookemail"` - **Not recommended for gpt-4o and newer models:** + - `"connector_sharepoint"` - 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. + - `defer_loading: optional boolean` - - `Text object { type }` + Whether this MCP tool is deferred and discovered via tool search. - Default response format. Used to generate text responses. + - `headers: optional map[string]` - - `type: "text"` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The type of response format being defined. Always `text`. + - `require_approval: optional object { always, never } or "always" or "never"` - - `"text"` + Specify which of the MCP server's tools require approval. - - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` + - `McpToolApprovalFilter object { always, never }` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `name: string` + - `always: optional object { read_only, tool_names }` - 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 filter object to specify which tools are allowed. - - `schema: map[unknown]` + - `read_only: optional boolean` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + 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: "json_schema"` + - `tool_names: optional array of string` - The type of response format being defined. Always `json_schema`. + List of allowed tool names. - - `"json_schema"` + - `never: optional object { read_only, tool_names }` - - `description: optional string` + A filter object to specify which tools are allowed. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `read_only: optional boolean` - - `strict: optional boolean` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - Whether to 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). + - `tool_names: optional array of string` - - `JSONObject object { type }` + List of allowed tool names. - 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. + - `McpToolApprovalSetting = "always" or "never"` - - `type: "json_object"` + 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 type of response format being defined. Always `json_object`. + - `"always"` - - `"json_object"` + - `"never"` - - `verbosity: optional "low" or "medium" or "high"` + - `server_description: optional string` - 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`. + Optional description of the MCP server, used to provide more context. - - `"low"` + - `server_url: optional string` - - `"medium"` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `"high"` + - `tunnel_id: optional string` - - `top_logprobs: optional number` + 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. - 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. + - `CodeInterpreter object { container, type, allowed_callers }` - - `truncation: optional "auto" or "disabled"` + A tool that runs Python code to help generate a response to a prompt. - The truncation strategy to use for the model response. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `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 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. - - `"auto"` + - `string` - - `"disabled"` + The container ID. - - `usage: optional BetaResponseUsage` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `input_tokens: number` + - `type: "auto"` - The number of input tokens. + Always `auto`. - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + - `"auto"` - A detailed breakdown of the input tokens. + - `file_ids: optional array of string` - - `cache_write_tokens: number` + An optional list of uploaded files to make available to your code. - The number of input tokens that were written to the cache. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `cached_tokens: number` + The memory limit for the code interpreter container. - The number of tokens that were retrieved from the cache. - [More on prompt caching](/docs/guides/prompt-caching). + - `"1g"` - - `output_tokens: number` + - `"4g"` - The number of output tokens. + - `"16g"` - - `output_tokens_details: object { reasoning_tokens }` + - `"64g"` - A detailed breakdown of the output tokens. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `reasoning_tokens: number` + Network access policy for the container. - The number of reasoning tokens. + - `BetaContainerNetworkPolicyDisabled object { type }` - - `total_tokens: number` + - `type: "disabled"` - The total number of tokens used. + Disable outbound network access. Always `disabled`. - - `user: optional string` + - `"disabled"` - 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). + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `sequence_number: number` + - `allowed_domains: array of string` - The sequence number for this event. + A list of allowed domains when type is `allowlist`. - - `type: "response.completed"` + - `type: "allowlist"` - The type of the event. Always `response.completed`. + Allow outbound network access only to specified domains. Always `allowlist`. - - `"response.completed"` + - `"allowlist"` - - `agent: optional object { agent_name }` + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - The agent that owns this multi-agent streaming event. + Optional domain-scoped secrets for allowlisted domains. - - `agent_name: string` + - `domain: string` - The canonical name of the agent that produced this item. + The domain associated with the secret. - - `BetaResponseContentPartAddedEvent object { content_index, item_id, output_index, 4 more }` + - `name: string` - Emitted when a new content part is added. + The name of the secret to inject for the domain. - - `content_index: number` + - `value: string` - The index of the content part that was added. + The secret value to inject for the domain. - - `item_id: string` + - `type: "code_interpreter"` - The ID of the output item that the content part was added to. + The type of the code interpreter tool. Always `code_interpreter`. - - `output_index: number` + - `"code_interpreter"` - The index of the output item that the content part was added to. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `part: BetaResponseOutputText or BetaResponseOutputRefusal or object { text, type }` + The tool invocation context(s). - The content part that was added. + - `"direct"` - - `BetaResponseOutputText object { annotations, logprobs, text, type }` + - `"programmatic"` - A text output from the model. + - `ProgrammaticToolCalling object { type }` - - `BetaResponseOutputRefusal object { refusal, type }` + - `type: "programmatic_tool_calling"` - A refusal from the model. + The type of the tool. Always `programmatic_tool_calling`. - - `ReasoningText object { text, type }` + - `"programmatic_tool_calling"` - Reasoning text from the model. + - `ImageGeneration object { type, action, background, 9 more }` - - `text: string` + A tool that generates images using the GPT image models. - The reasoning text from the model. + - `type: "image_generation"` - - `type: "reasoning_text"` + The type of the image generation tool. Always `image_generation`. - The type of the reasoning text. Always `reasoning_text`. + - `"image_generation"` - - `"reasoning_text"` + - `action: optional "generate" or "edit" or "auto"` - - `sequence_number: number` + Whether to generate a new image or edit an existing image. Default: `auto`. - The sequence number of this event. + - `"generate"` - - `type: "response.content_part.added"` + - `"edit"` - The type of the event. Always `response.content_part.added`. + - `"auto"` - - `"response.content_part.added"` + - `background: optional "transparent" or "opaque" or "auto"` - - `agent: optional object { agent_name }` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - The agent that owns this multi-agent streaming event. + - `"transparent"` - - `agent_name: string` + - `"opaque"` - The canonical name of the agent that produced this item. + - `"auto"` - - `BetaResponseContentPartDoneEvent object { content_index, item_id, output_index, 4 more }` + - `input_fidelity: optional "high" or "low"` - Emitted when a content part is done. + 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`. - - `content_index: number` + - `"high"` - The index of the content part that is done. + - `"low"` - - `item_id: string` + - `input_image_mask: optional object { file_id, image_url }` - The ID of the output item that the content part was added to. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `output_index: number` + - `file_id: optional string` - The index of the output item that the content part was added to. + File ID for the mask image. - - `part: BetaResponseOutputText or BetaResponseOutputRefusal or object { text, type }` + - `image_url: optional string` - The content part that is done. + Base64-encoded mask image. - - `BetaResponseOutputText object { annotations, logprobs, text, type }` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - A text output from the model. + The image generation model to use. Default: `gpt-image-1`. - - `BetaResponseOutputRefusal object { refusal, type }` + - `string` - A refusal from the model. + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `ReasoningText object { text, type }` + The image generation model to use. Default: `gpt-image-1`. - Reasoning text from the model. + - `"gpt-image-1"` - - `text: string` + - `"gpt-image-1-mini"` - The reasoning text from the model. + - `"gpt-image-1.5"` - - `type: "reasoning_text"` + - `moderation: optional "auto" or "low"` - The type of the reasoning text. Always `reasoning_text`. + Moderation level for the generated image. Default: `auto`. - - `"reasoning_text"` + - `"auto"` - - `sequence_number: number` + - `"low"` - The sequence number of this event. + - `output_compression: optional number` - - `type: "response.content_part.done"` + Compression level for the output image. Default: 100. - The type of the event. Always `response.content_part.done`. + - `output_format: optional "png" or "webp" or "jpeg"` - - `"response.content_part.done"` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `agent: optional object { agent_name }` + - `"png"` - The agent that owns this multi-agent streaming event. + - `"webp"` - - `agent_name: string` + - `"jpeg"` - The canonical name of the agent that produced this item. + - `partial_images: optional number` - - `BetaResponseCreatedEvent object { response, sequence_number, type, agent }` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - An event that is emitted when a response is created. + - `quality: optional "low" or "medium" or "high" or "auto"` - - `response: BetaResponse` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - The response that was created. + - `"low"` - - `sequence_number: number` + - `"medium"` - The sequence number for this event. + - `"high"` - - `type: "response.created"` + - `"auto"` - The type of the event. Always `response.created`. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `"response.created"` + 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`. - - `agent: optional object { agent_name }` + - `string` - The agent that owns this multi-agent streaming event. + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `agent_name: string` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - The canonical name of the agent that produced this item. + - `"1024x1024"` - - `BetaResponseErrorEvent object { code, message, param, 3 more }` + - `"1024x1536"` - Emitted when an error occurs. + - `"1536x1024"` - - `code: string` + - `"auto"` - The error code. + - `LocalShell object { type }` - - `message: string` + A tool that allows the model to execute shell commands in a local environment. - The error message. + - `type: "local_shell"` - - `param: string` + The type of the local shell tool. Always `local_shell`. - The error parameter. + - `"local_shell"` - - `sequence_number: number` + - `Shell object { type, allowed_callers, environment }` - The sequence number of this event. + A tool that allows the model to execute shell commands. - - `type: "error"` + - `type: "shell"` - The type of the event. Always `error`. + The type of the shell tool. Always `shell`. - - `"error"` + - `"shell"` - - `agent: optional object { agent_name }` + - `allowed_callers: optional array of "direct" or "programmatic"` - The agent that owns this multi-agent streaming event. + The tool invocation context(s). - - `agent_name: string` + - `"direct"` - The canonical name of the agent that produced this item. + - `"programmatic"` - - `BetaResponseFileSearchCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - Emitted when a file search call is completed (results found). + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `item_id: string` + - `type: "container_auto"` - The ID of the output item that the file search call is initiated. + Automatically creates a container for this request - - `output_index: number` + - `"container_auto"` - The index of the output item that the file search call is initiated. + - `file_ids: optional array of string` - - `sequence_number: number` + An optional list of uploaded files to make available to your code. - The sequence number of this event. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `type: "response.file_search_call.completed"` + The memory limit for the container. - The type of the event. Always `response.file_search_call.completed`. + - `"1g"` - - `"response.file_search_call.completed"` + - `"4g"` - - `agent: optional object { agent_name }` + - `"16g"` - The agent that owns this multi-agent streaming event. + - `"64g"` - - `agent_name: string` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - The canonical name of the agent that produced this item. + Network access policy for the container. - - `BetaResponseFileSearchCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + - `BetaContainerNetworkPolicyDisabled object { type }` - Emitted when a file search call is initiated. + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `item_id: string` + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - The ID of the output item that the file search call is initiated. + An optional list of skills referenced by id or inline data. - - `output_index: number` + - `BetaSkillReference object { skill_id, type, version }` - The index of the output item that the file search call is initiated. + - `skill_id: string` - - `sequence_number: number` + The ID of the referenced skill. - The sequence number of this event. + - `type: "skill_reference"` - - `type: "response.file_search_call.in_progress"` + References a skill created with the /v1/skills endpoint. - The type of the event. Always `response.file_search_call.in_progress`. + - `"skill_reference"` - - `"response.file_search_call.in_progress"` + - `version: optional string` - - `agent: optional object { agent_name }` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - The agent that owns this multi-agent streaming event. + - `BetaInlineSkill object { description, name, source, type }` - - `agent_name: string` + - `description: string` - The canonical name of the agent that produced this item. + The description of the skill. - - `BetaResponseFileSearchCallSearchingEvent object { item_id, output_index, sequence_number, 2 more }` + - `name: string` - Emitted when a file search is currently searching. + The name of the skill. - - `item_id: string` + - `source: BetaInlineSkillSource` - The ID of the output item that the file search call is initiated. + Inline skill payload - - `output_index: number` + - `data: string` - The index of the output item that the file search call is searching. + Base64-encoded skill zip bundle. - - `sequence_number: number` + - `media_type: "application/zip"` - The sequence number of this event. + The media type of the inline skill payload. Must be `application/zip`. - - `type: "response.file_search_call.searching"` + - `"application/zip"` - The type of the event. Always `response.file_search_call.searching`. + - `type: "base64"` - - `"response.file_search_call.searching"` + The type of the inline skill source. Must be `base64`. - - `agent: optional object { agent_name }` + - `"base64"` - The agent that owns this multi-agent streaming event. + - `type: "inline"` - - `agent_name: string` + Defines an inline skill for this request. - The canonical name of the agent that produced this item. + - `"inline"` - - `BetaResponseFunctionCallArgumentsDeltaEvent object { delta, item_id, output_index, 3 more }` + - `BetaLocalEnvironment object { type, skills }` - Emitted when there is a partial function-call arguments delta. + - `type: "local"` - - `delta: string` + Use a local computer environment. - The function-call arguments delta that is added. + - `"local"` - - `item_id: string` + - `skills: optional array of BetaLocalSkill` - The ID of the output item that the function-call arguments delta is added to. + An optional list of skills. - - `output_index: number` + - `description: string` - The index of the output item that the function-call arguments delta is added to. + The description of the skill. - - `sequence_number: number` + - `name: string` - The sequence number of this event. + The name of the skill. - - `type: "response.function_call_arguments.delta"` + - `path: string` - The type of the event. Always `response.function_call_arguments.delta`. + The path to the directory containing the skill. - - `"response.function_call_arguments.delta"` + - `BetaContainerReference object { container_id, type }` - - `agent: optional object { agent_name }` + - `container_id: string` - The agent that owns this multi-agent streaming event. + The ID of the referenced container. - - `agent_name: string` + - `type: "container_reference"` - The canonical name of the agent that produced this item. + References a container created with the /v1/containers endpoint - - `BetaResponseFunctionCallArgumentsDoneEvent object { arguments, item_id, name, 4 more }` + - `"container_reference"` - Emitted when function-call arguments are finalized. + - `Custom object { name, type, allowed_callers, 3 more }` - - `arguments: string` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - The function-call arguments. + - `name: string` - - `item_id: string` + The name of the custom tool, used to identify it in tool calls. - The ID of the item. + - `type: "custom"` - - `name: string` + The type of the custom tool. Always `custom`. - The name of the function that was called. + - `"custom"` - - `output_index: number` + - `allowed_callers: optional array of "direct" or "programmatic"` - The index of the output item. + The tool invocation context(s). - - `sequence_number: number` + - `"direct"` - The sequence number of this event. + - `"programmatic"` - - `type: "response.function_call_arguments.done"` + - `defer_loading: optional boolean` - - `"response.function_call_arguments.done"` + Whether this tool should be deferred and discovered via tool search. - - `agent: optional object { agent_name }` + - `description: optional string` - The agent that owns this multi-agent streaming event. + Optional description of the custom tool, used to provide more context. - - `agent_name: string` + - `format: optional object { type } or object { definition, syntax, type }` - The canonical name of the agent that produced this item. + The input format for the custom tool. Default is unconstrained text. - - `BetaResponseInProgressEvent object { response, sequence_number, type, agent }` + - `Text object { type }` - Emitted when the response is in progress. + Unconstrained free-form text. - - `response: BetaResponse` + - `type: "text"` - The response that is in progress. + Unconstrained text format. Always `text`. - - `sequence_number: number` + - `"text"` - The sequence number of this event. + - `Grammar object { definition, syntax, type }` - - `type: "response.in_progress"` + A grammar defined by the user. - The type of the event. Always `response.in_progress`. + - `definition: string` - - `"response.in_progress"` + The grammar definition. - - `agent: optional object { agent_name }` + - `syntax: "lark" or "regex"` - The agent that owns this multi-agent streaming event. + The syntax of the grammar definition. One of `lark` or `regex`. - - `agent_name: string` + - `"lark"` - The canonical name of the agent that produced this item. + - `"regex"` - - `BetaResponseFailedEvent object { response, sequence_number, type, agent }` + - `type: "grammar"` - An event that is emitted when a response fails. + Grammar format. Always `grammar`. - - `response: BetaResponse` + - `"grammar"` - The response that failed. + - `Namespace object { description, name, tools, type }` - - `sequence_number: number` + Groups function/custom tools under a shared namespace. - The sequence number of this event. + - `description: string` - - `type: "response.failed"` + A description of the namespace shown to the model. - The type of the event. Always `response.failed`. + - `name: string` - - `"response.failed"` + The namespace name used in tool calls (for example, `crm`). - - `agent: optional object { agent_name }` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - The agent that owns this multi-agent streaming event. + The function/custom tools available inside this namespace. - - `agent_name: string` + - `Function object { name, type, allowed_callers, 5 more }` - The canonical name of the agent that produced this item. + - `name: string` - - `BetaResponseIncompleteEvent object { response, sequence_number, type, agent }` + - `type: "function"` - An event that is emitted when a response finishes as incomplete. + - `"function"` - - `response: BetaResponse` + - `allowed_callers: optional array of "direct" or "programmatic"` - The response that was incomplete. + The tool invocation context(s). - - `sequence_number: number` + - `"direct"` - The sequence number of this event. + - `"programmatic"` - - `type: "response.incomplete"` + - `defer_loading: optional boolean` - The type of the event. Always `response.incomplete`. + Whether this function should be deferred and discovered via tool search. - - `"response.incomplete"` + - `description: optional string` - - `agent: optional object { agent_name }` + - `output_schema: optional map[unknown]` - The agent that owns this multi-agent streaming event. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `agent_name: string` + - `parameters: optional unknown` - The canonical name of the agent that produced this item. + - `strict: optional boolean` - - `BetaResponseOutputItemAddedEvent object { item, output_index, sequence_number, 2 more }` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - Emitted when a new output item is added. + - `Custom object { name, type, allowed_callers, 3 more }` - - `item: BetaResponseOutputItem` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - The output item that was added. + - `name: string` - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + The name of the custom tool, used to identify it in tool calls. - An output message from the model. + - `type: "custom"` - - `FileSearchCall object { id, queries, status, 3 more }` + The type of the custom tool. Always `custom`. - The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + - `"custom"` - - `FunctionCall object { arguments, call_id, name, 6 more }` + - `allowed_callers: optional array of "direct" or "programmatic"` - A tool call to run a function. See the - [function calling guide](/docs/guides/function-calling) for more information. + The tool invocation context(s). - - `FunctionCallOutput object { id, call_id, output, 5 more }` + - `"direct"` - - `AgentMessage object { id, author, content, 3 more }` + - `"programmatic"` - - `MultiAgentCall object { id, action, arguments, 3 more }` + - `defer_loading: optional boolean` - - `MultiAgentCallOutput object { id, action, call_id, 3 more }` + Whether this tool should be deferred and discovered via tool search. - - `WebSearchCall object { id, action, status, 2 more }` + - `description: optional string` - The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + Optional description of the custom tool, used to provide more context. - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + - `format: optional object { type } or object { definition, syntax, type }` - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + The input format for the custom tool. Default is unconstrained text. - - `ComputerCallOutput object { id, call_id, output, 5 more }` + - `Text object { type }` - - `Reasoning object { id, summary, type, 4 more }` + Unconstrained free-form text. - 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: "text"` - - `Program object { id, call_id, code, 3 more }` + Unconstrained text format. Always `text`. - - `ProgramOutput object { id, call_id, result, 3 more }` + - `"text"` - - `ToolSearchCall object { id, arguments, call_id, 5 more }` + - `Grammar object { definition, syntax, type }` - - `ToolSearchOutput object { id, call_id, execution, 5 more }` + A grammar defined by the user. - - `AdditionalTools object { id, role, tools, 2 more }` + - `definition: string` - - `Compaction object { id, encrypted_content, type, 2 more }` + The grammar definition. - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + - `syntax: "lark" or "regex"` - - `ImageGenerationCall object { id, result, status, 2 more }` + The syntax of the grammar definition. One of `lark` or `regex`. - An image generation request made by the model. + - `"lark"` - - `CodeInterpreterCall object { id, code, container_id, 4 more }` + - `"regex"` - A tool call to run code. + - `type: "grammar"` - - `LocalShellCall object { id, action, call_id, 3 more }` + Grammar format. Always `grammar`. - A tool call to run a command on the local shell. + - `"grammar"` - - `LocalShellCallOutput object { id, output, type, 2 more }` + - `type: "namespace"` - The output of a local shell tool call. + The type of the tool. Always `namespace`. - - `ShellCall object { id, action, call_id, 6 more }` + - `"namespace"` - A tool call that executes one or more shell commands in a managed environment. + - `ToolSearch object { type, description, execution, parameters }` - - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` + Hosted or BYOT tool search configuration for deferred tools. - The output of a shell tool call that was emitted. + - `type: "tool_search"` - - `ApplyPatchCall object { id, call_id, operation, 5 more }` + The type of the tool. Always `tool_search`. - A tool call that applies file diffs by creating, deleting, or updating files. + - `"tool_search"` - - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` + - `description: optional string` - The output emitted by an apply patch tool call. + Description shown to the model for a client-executed tool search tool. - - `McpCall object { id, arguments, name, 7 more }` + - `execution: optional "server" or "client"` - An invocation of a tool on an MCP server. + Whether tool search is executed by the server or by the client. - - `McpListTools object { id, server_label, tools, 3 more }` + - `"server"` - A list of tools available on an MCP server. + - `"client"` - - `McpApprovalRequest object { id, arguments, name, 3 more }` + - `parameters: optional unknown` - A request for human approval of a tool invocation. + Parameter schema for a client-executed tool search tool. - - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - A response to an MCP approval request. + 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). - - `CustomToolCall object { call_id, input, name, 5 more }` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - A call to a custom tool created by the model. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `CustomToolCallOutput object { id, call_id, output, 5 more }` + - `"web_search_preview"` - - `output_index: number` + - `"web_search_preview_2025_03_11"` - The index of the output item that was added. + - `search_content_types: optional array of "text" or "image"` - - `sequence_number: number` + - `"text"` - The sequence number of this event. + - `"image"` - - `type: "response.output_item.added"` + - `search_context_size: optional "low" or "medium" or "high"` - The type of the event. Always `response.output_item.added`. + 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. - - `"response.output_item.added"` + - `"low"` - - `agent: optional object { agent_name }` + - `"medium"` - The agent that owns this multi-agent streaming event. + - `"high"` - - `agent_name: string` + - `user_location: optional object { type, city, country, 2 more }` - The canonical name of the agent that produced this item. + The user's location. - - `BetaResponseOutputItemDoneEvent object { item, output_index, sequence_number, 2 more }` + - `type: "approximate"` - Emitted when an output item is marked done. + The type of location approximation. Always `approximate`. - - `item: BetaResponseOutputItem` + - `"approximate"` - The output item that was marked done. + - `city: optional string` - - `output_index: number` + Free text input for the city of the user, e.g. `San Francisco`. - The index of the output item that was marked done. + - `country: optional string` - - `sequence_number: number` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The sequence number of this event. + - `region: optional string` - - `type: "response.output_item.done"` + Free text input for the region of the user, e.g. `California`. - The type of the event. Always `response.output_item.done`. + - `timezone: optional string` - - `"response.output_item.done"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `agent: optional object { agent_name }` + - `ApplyPatch object { type, allowed_callers }` - The agent that owns this multi-agent streaming event. + Allows the assistant to create, delete, or update files using unified diffs. - - `agent_name: string` + - `type: "apply_patch"` - The canonical name of the agent that produced this item. + The type of the tool. Always `apply_patch`. - - `BetaResponseReasoningSummaryPartAddedEvent object { item_id, output_index, part, 4 more }` + - `"apply_patch"` - Emitted when a new reasoning summary part is added. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `item_id: string` + The tool invocation context(s). - The ID of the item this summary part is associated with. + - `"direct"` - - `output_index: number` + - `"programmatic"` - The index of the output item this summary part is associated with. + - `type: "tool_search_output"` - - `part: object { text, type }` + The item type. Always `tool_search_output`. - The summary part that was added. + - `"tool_search_output"` - - `text: string` + - `id: optional string` - The text of the summary part. + The unique ID of this tool search output. - - `type: "summary_text"` + - `agent: optional object { agent_name }` - The type of the summary part. Always `summary_text`. + The agent that produced this item. - - `"summary_text"` + - `agent_name: string` - - `sequence_number: number` + The canonical name of the agent that produced this item. - The sequence number of this event. + - `call_id: optional string` - - `summary_index: number` + The unique ID of the tool search call generated by the model. - The index of the summary part within the reasoning summary. + - `execution: optional "server" or "client"` - - `type: "response.reasoning_summary_part.added"` + Whether tool search was executed by the server or by the client. - The type of the event. Always `response.reasoning_summary_part.added`. + - `"server"` - - `"response.reasoning_summary_part.added"` + - `"client"` - - `agent: optional object { agent_name }` + - `status: optional "in_progress" or "completed" or "incomplete"` - The agent that owns this multi-agent streaming event. + The status of the tool search output. - - `agent_name: string` + - `"in_progress"` - The canonical name of the agent that produced this item. + - `"completed"` - - `BetaResponseReasoningSummaryPartDoneEvent object { item_id, output_index, part, 5 more }` + - `"incomplete"` - Emitted when a reasoning summary part is completed. + - `AdditionalTools object { role, tools, type, 2 more }` - - `item_id: string` + - `role: "developer"` - The ID of the item this summary part is associated with. + The role that provided the additional tools. Only `developer` is supported. - - `output_index: number` + - `"developer"` - The index of the output item this summary part is associated with. + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - - `part: object { text, type }` + A list of additional tools made available at this item. - The completed summary part. + - `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 text of the summary part. + - `name: string` - - `type: "summary_text"` + The name of the function to call. - The type of the summary part. Always `summary_text`. + - `parameters: map[unknown]` - - `"summary_text"` + A JSON schema object describing the parameters of the function. - - `sequence_number: number` + - `strict: boolean` - The sequence number of this event. + Whether strict parameter validation is enforced for this function tool. - - `summary_index: number` + - `type: "function"` - The index of the summary part within the reasoning summary. + The type of the function tool. Always `function`. - - `type: "response.reasoning_summary_part.done"` + - `"function"` - The type of the event. Always `response.reasoning_summary_part.done`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"response.reasoning_summary_part.done"` + The tool invocation context(s). - - `agent: optional object { agent_name }` + - `"direct"` - The agent that owns this multi-agent streaming event. + - `"programmatic"` - - `agent_name: string` + - `defer_loading: optional boolean` - The canonical name of the agent that produced this item. + Whether this function is deferred and loaded via tool search. - - `status: optional "incomplete"` + - `description: optional string` - The completion status of the summary part. Omitted when the part completed - normally and set to `incomplete` when generation was interrupted. + A description of the function. Used by the model to determine whether or not to call the function. - - `"incomplete"` + - `output_schema: optional map[unknown]` - - `BetaResponseReasoningSummaryTextDeltaEvent object { delta, item_id, output_index, 4 more }` + A JSON schema object describing the JSON value encoded in string outputs for this function. - Emitted when a delta is added to a reasoning summary text. + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `delta: 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 delta that was added to the summary. + - `type: "file_search"` - - `item_id: string` + The type of the file search tool. Always `file_search`. - The ID of the item this summary text delta is associated with. + - `"file_search"` - - `output_index: number` + - `vector_store_ids: array of string` - The index of the output item this summary text delta is associated with. + The IDs of the vector stores to search. - - `sequence_number: number` + - `filters: optional object { key, type, value } or object { filters, type }` - The sequence number of this event. + A filter to apply. - - `summary_index: number` + - `ComparisonFilter object { key, type, value }` - The index of the summary part within the reasoning summary. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `type: "response.reasoning_summary_text.delta"` + - `key: string` - The type of the event. Always `response.reasoning_summary_text.delta`. + The key to compare against the value. - - `"response.reasoning_summary_text.delta"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `agent: optional object { agent_name }` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The agent that owns this multi-agent streaming event. + - `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 - - `agent_name: string` + - `"eq"` - The canonical name of the agent that produced this item. + - `"ne"` - - `BetaResponseReasoningSummaryTextDoneEvent object { item_id, output_index, sequence_number, 4 more }` + - `"gt"` - Emitted when a reasoning summary text is completed. + - `"gte"` - - `item_id: string` + - `"lt"` - The ID of the item this summary text is associated with. + - `"lte"` - - `output_index: number` + - `"in"` - The index of the output item this summary text is associated with. + - `"nin"` - - `sequence_number: number` + - `value: string or number or boolean or array of string or number` - The sequence number of this event. + The value to compare against the attribute key; supports string, number, or boolean types. - - `summary_index: number` + - `string` - The index of the summary part within the reasoning summary. + - `number` - - `text: string` + - `boolean` - The full text of the completed reasoning summary. + - `array of string or number` - - `type: "response.reasoning_summary_text.done"` + - `string` - The type of the event. Always `response.reasoning_summary_text.done`. + - `number` - - `"response.reasoning_summary_text.done"` + - `CompoundFilter object { filters, type }` - - `agent: optional object { agent_name }` + Combine multiple filters using `and` or `or`. - The agent that owns this multi-agent streaming event. + - `filters: array of object { key, type, value } or unknown` - - `agent_name: string` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The canonical name of the agent that produced this item. + - `ComparisonFilter object { key, type, value }` - - `BetaResponseReasoningTextDeltaEvent object { content_index, delta, item_id, 4 more }` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - Emitted when a delta is added to a reasoning text. + - `key: string` - - `content_index: number` + The key to compare against the value. - The index of the reasoning content part this delta is associated with. + - `type: "eq" or "ne" or "gt" or 5 more` - - `delta: string` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The text delta that was added to the reasoning content. + - `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 - - `item_id: string` + - `"eq"` - The ID of the item this reasoning text delta is associated with. + - `"ne"` - - `output_index: number` + - `"gt"` - The index of the output item this reasoning text delta is associated with. + - `"gte"` - - `sequence_number: number` + - `"lt"` - The sequence number of this event. + - `"lte"` - - `type: "response.reasoning_text.delta"` + - `"in"` - The type of the event. Always `response.reasoning_text.delta`. + - `"nin"` - - `"response.reasoning_text.delta"` + - `value: string or number or boolean or array of string or number` - - `agent: optional object { agent_name }` + The value to compare against the attribute key; supports string, number, or boolean types. - The agent that owns this multi-agent streaming event. + - `string` - - `agent_name: string` + - `number` - The canonical name of the agent that produced this item. + - `boolean` - - `BetaResponseReasoningTextDoneEvent object { content_index, item_id, output_index, 4 more }` + - `array of string or number` - Emitted when a reasoning text is completed. + - `string` - - `content_index: number` + - `number` - The index of the reasoning content part. + - `unknown` - - `item_id: string` + - `type: "and" or "or"` - The ID of the item this reasoning text is associated with. + Type of operation: `and` or `or`. - - `output_index: number` + - `"and"` - The index of the output item this reasoning text is associated with. + - `"or"` - - `sequence_number: number` + - `max_num_results: optional number` - The sequence number of this event. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `text: string` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - The full text of the completed reasoning content. + Ranking options for search. - - `type: "response.reasoning_text.done"` + - `hybrid_search: optional object { embedding_weight, text_weight }` - The type of the event. Always `response.reasoning_text.done`. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `"response.reasoning_text.done"` + - `embedding_weight: number` - - `agent: optional object { agent_name }` + The weight of the embedding in the reciprocal ranking fusion. - The agent that owns this multi-agent streaming event. + - `text_weight: number` - - `agent_name: string` + The weight of the text in the reciprocal ranking fusion. - The canonical name of the agent that produced this item. + - `ranker: optional "auto" or "default-2024-11-15"` - - `BetaResponseRefusalDeltaEvent object { content_index, delta, item_id, 4 more }` + The ranker to use for the file search. - Emitted when there is a partial refusal text. + - `"auto"` - - `content_index: number` + - `"default-2024-11-15"` - The index of the content part that the refusal text is added to. + - `score_threshold: optional number` - - `delta: 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 refusal text that is added. + - `Computer object { type }` - - `item_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 output item that the refusal text is added to. + - `type: "computer"` - - `output_index: number` + The type of the computer tool. Always `computer`. - The index of the output item that the refusal text is added to. + - `"computer"` - - `sequence_number: number` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - The sequence number of this event. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `type: "response.refusal.delta"` + - `display_height: number` - The type of the event. Always `response.refusal.delta`. + The height of the computer display. - - `"response.refusal.delta"` + - `display_width: number` - - `agent: optional object { agent_name }` + The width of the computer display. - The agent that owns this multi-agent streaming event. + - `environment: "windows" or "mac" or "linux" or 2 more` - - `agent_name: string` + The type of computer environment to control. - The canonical name of the agent that produced this item. + - `"windows"` - - `BetaResponseRefusalDoneEvent object { content_index, item_id, output_index, 4 more }` + - `"mac"` - Emitted when refusal text is finalized. + - `"linux"` - - `content_index: number` + - `"ubuntu"` - The index of the content part that the refusal text is finalized. + - `"browser"` - - `item_id: string` + - `type: "computer_use_preview"` - The ID of the output item that the refusal text is finalized. + The type of the computer use tool. Always `computer_use_preview`. - - `output_index: number` + - `"computer_use_preview"` - The index of the output item that the refusal text is finalized. + - `WebSearch object { type, filters, search_context_size, user_location }` - - `refusal: string` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - The refusal text that is finalized. + - `type: "web_search" or "web_search_2025_08_26"` - - `sequence_number: number` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - The sequence number of this event. + - `"web_search"` - - `type: "response.refusal.done"` + - `"web_search_2025_08_26"` - The type of the event. Always `response.refusal.done`. + - `filters: optional object { allowed_domains }` - - `"response.refusal.done"` + Filters for the search. - - `agent: optional object { agent_name }` + - `allowed_domains: optional array of string` - The agent that owns this multi-agent streaming event. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `agent_name: string` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - The canonical name of the agent that produced this item. + - `search_context_size: optional "low" or "medium" or "high"` - - `BetaResponseTextDeltaEvent object { content_index, delta, item_id, 5 more }` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - Emitted when there is an additional text delta. + - `"low"` - - `content_index: number` + - `"medium"` - The index of the content part that the text delta was added to. + - `"high"` - - `delta: string` + - `user_location: optional object { city, country, region, 2 more }` - The text delta that was added. + The approximate location of the user. - - `item_id: string` + - `city: optional string` - The ID of the output item that the text delta was added to. + Free text input for the city of the user, e.g. `San Francisco`. - - `logprobs: array of object { token, logprob, top_logprobs }` + - `country: optional string` - The log probabilities of the tokens in the delta. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `token: string` + - `region: optional string` - A possible text token. + Free text input for the region of the user, e.g. `California`. - - `logprob: number` + - `timezone: optional string` - The log probability of this token. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `top_logprobs: optional array of object { token, logprob }` + - `type: optional "approximate"` - The log probabilities of up to 20 of the most likely tokens. + The type of location approximation. Always `approximate`. - - `token: optional string` + - `"approximate"` - A possible text token. + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `logprob: optional number` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - The log probability of this token. + - `server_label: string` - - `output_index: number` + A label for this MCP server, used to identify it in tool calls. - The index of the output item that the text delta was added to. + - `type: "mcp"` - - `sequence_number: number` + The type of the MCP tool. Always `mcp`. - The sequence number for this event. + - `"mcp"` - - `type: "response.output_text.delta"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The type of the event. Always `response.output_text.delta`. + The tool invocation context(s). - - `"response.output_text.delta"` + - `"direct"` - - `agent: optional object { agent_name }` + - `"programmatic"` - The agent that owns this multi-agent streaming event. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `agent_name: string` + List of allowed tool names or a filter object. - The canonical name of the agent that produced this item. + - `McpAllowedTools = array of string` - - `BetaResponseTextDoneEvent object { content_index, item_id, logprobs, 5 more }` + A string array of allowed tool names - Emitted when text content is finalized. + - `McpToolFilter object { read_only, tool_names }` - - `content_index: number` + A filter object to specify which tools are allowed. - The index of the content part that the text content is finalized. + - `read_only: optional boolean` - - `item_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 output item that the text content is finalized. + - `tool_names: optional array of string` - - `logprobs: array of object { token, logprob, top_logprobs }` + List of allowed tool names. - The log probabilities of the tokens in the delta. + - `authorization: optional string` - - `token: string` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - A possible text token. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `logprob: number` + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). - The log probability of this token. + Currently supported `connector_id` values are: - - `top_logprobs: optional array of object { token, logprob }` + - 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 log probabilities of up to 20 of the most likely tokens. + - `"connector_dropbox"` - - `token: optional string` + - `"connector_gmail"` - A possible text token. + - `"connector_googlecalendar"` - - `logprob: optional number` + - `"connector_googledrive"` - The log probability of this token. + - `"connector_microsoftteams"` - - `output_index: number` + - `"connector_outlookcalendar"` - The index of the output item that the text content is finalized. + - `"connector_outlookemail"` - - `sequence_number: number` + - `"connector_sharepoint"` - The sequence number for this event. + - `defer_loading: optional boolean` - - `text: string` + Whether this MCP tool is deferred and discovered via tool search. - The text content that is finalized. + - `headers: optional map[string]` - - `type: "response.output_text.done"` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The type of the event. Always `response.output_text.done`. + - `require_approval: optional object { always, never } or "always" or "never"` - - `"response.output_text.done"` + Specify which of the MCP server's tools require approval. - - `agent: optional object { agent_name }` + - `McpToolApprovalFilter object { always, never }` - The agent that owns this multi-agent streaming event. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `agent_name: string` + - `always: optional object { read_only, tool_names }` - The canonical name of the agent that produced this item. + A filter object to specify which tools are allowed. - - `BetaResponseWebSearchCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` + - `read_only: optional boolean` - Emitted when a web search call is completed. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `item_id: string` + - `tool_names: optional array of string` - Unique ID for the output item associated with the web search call. + List of allowed tool names. - - `output_index: number` + - `never: optional object { read_only, tool_names }` - The index of the output item that the web search call is associated with. + A filter object to specify which tools are allowed. - - `sequence_number: number` + - `read_only: optional boolean` - The sequence number of the web search call being processed. + 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: "response.web_search_call.completed"` + - `tool_names: optional array of string` - The type of the event. Always `response.web_search_call.completed`. + List of allowed tool names. - - `"response.web_search_call.completed"` + - `McpToolApprovalSetting = "always" or "never"` - - `agent: optional object { agent_name }` + 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 agent that owns this multi-agent streaming event. + - `"always"` - - `agent_name: string` + - `"never"` - The canonical name of the agent that produced this item. + - `server_description: optional string` - - `BetaResponseWebSearchCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + Optional description of the MCP server, used to provide more context. - Emitted when a web search call is initiated. + - `server_url: optional string` - - `item_id: string` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - Unique ID for the output item associated with the web search call. + - `tunnel_id: optional string` - - `output_index: number` + 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 index of the output item that the web search call is associated with. + - `CodeInterpreter object { container, type, allowed_callers }` - - `sequence_number: number` + A tool that runs Python code to help generate a response to a prompt. - The sequence number of the web search call being processed. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `type: "response.web_search_call.in_progress"` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - The type of the event. Always `response.web_search_call.in_progress`. + - `string` - - `"response.web_search_call.in_progress"` + The container ID. - - `agent: optional object { agent_name }` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - The agent that owns this multi-agent streaming event. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `agent_name: string` + - `type: "auto"` - The canonical name of the agent that produced this item. + Always `auto`. - - `BetaResponseWebSearchCallSearchingEvent object { item_id, output_index, sequence_number, 2 more }` + - `"auto"` - Emitted when a web search call is executing. + - `file_ids: optional array of string` - - `item_id: string` + An optional list of uploaded files to make available to your code. - Unique ID for the output item associated with the web search call. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `output_index: number` + The memory limit for the code interpreter container. - The index of the output item that the web search call is associated with. + - `"1g"` - - `sequence_number: number` + - `"4g"` - The sequence number of the web search call being processed. + - `"16g"` - - `type: "response.web_search_call.searching"` + - `"64g"` - The type of the event. Always `response.web_search_call.searching`. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `"response.web_search_call.searching"` + Network access policy for the container. - - `agent: optional object { agent_name }` + - `BetaContainerNetworkPolicyDisabled object { type }` - The agent that owns this multi-agent streaming event. + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `agent_name: string` + - `type: "code_interpreter"` - The canonical name of the agent that produced this item. + The type of the code interpreter tool. Always `code_interpreter`. - - `BetaResponseImageGenCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` + - `"code_interpreter"` - Emitted when an image generation tool call has completed and the final image is available. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `item_id: string` + The tool invocation context(s). - The unique identifier of the image generation item being processed. + - `"direct"` - - `output_index: number` + - `"programmatic"` - The index of the output item in the response's output array. + - `ProgrammaticToolCalling object { type }` - - `sequence_number: number` + - `type: "programmatic_tool_calling"` - The sequence number of this event. + The type of the tool. Always `programmatic_tool_calling`. - - `type: "response.image_generation_call.completed"` + - `"programmatic_tool_calling"` - The type of the event. Always 'response.image_generation_call.completed'. + - `ImageGeneration object { type, action, background, 9 more }` - - `"response.image_generation_call.completed"` + A tool that generates images using the GPT image models. - - `agent: optional object { agent_name }` + - `type: "image_generation"` - The agent that owns this multi-agent streaming event. + The type of the image generation tool. Always `image_generation`. - - `agent_name: string` + - `"image_generation"` - The canonical name of the agent that produced this item. + - `action: optional "generate" or "edit" or "auto"` - - `BetaResponseImageGenCallGeneratingEvent object { item_id, output_index, sequence_number, 2 more }` + Whether to generate a new image or edit an existing image. Default: `auto`. - Emitted when an image generation tool call is actively generating an image (intermediate state). + - `"generate"` - - `item_id: string` + - `"edit"` - The unique identifier of the image generation item being processed. + - `"auto"` - - `output_index: number` + - `background: optional "transparent" or "opaque" or "auto"` - The index of the output item in the response's output array. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `sequence_number: number` + - `"transparent"` - The sequence number of the image generation item being processed. + - `"opaque"` - - `type: "response.image_generation_call.generating"` + - `"auto"` - The type of the event. Always 'response.image_generation_call.generating'. + - `input_fidelity: optional "high" or "low"` - - `"response.image_generation_call.generating"` + 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`. - - `agent: optional object { agent_name }` + - `"high"` - The agent that owns this multi-agent streaming event. + - `"low"` - - `agent_name: string` + - `input_image_mask: optional object { file_id, image_url }` - The canonical name of the agent that produced this item. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `BetaResponseImageGenCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + - `file_id: optional string` - Emitted when an image generation tool call is in progress. + File ID for the mask image. - - `item_id: string` + - `image_url: optional string` - The unique identifier of the image generation item being processed. + Base64-encoded mask image. - - `output_index: number` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The index of the output item in the response's output array. + The image generation model to use. Default: `gpt-image-1`. - - `sequence_number: number` + - `string` - The sequence number of the image generation item being processed. + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `type: "response.image_generation_call.in_progress"` + The image generation model to use. Default: `gpt-image-1`. - The type of the event. Always 'response.image_generation_call.in_progress'. + - `"gpt-image-1"` - - `"response.image_generation_call.in_progress"` + - `"gpt-image-1-mini"` - - `agent: optional object { agent_name }` + - `"gpt-image-1.5"` - The agent that owns this multi-agent streaming event. + - `moderation: optional "auto" or "low"` - - `agent_name: string` + Moderation level for the generated image. Default: `auto`. - The canonical name of the agent that produced this item. + - `"auto"` - - `BetaResponseImageGenCallPartialImageEvent object { item_id, output_index, partial_image_b64, 4 more }` + - `"low"` - Emitted when a partial image is available during image generation streaming. + - `output_compression: optional number` - - `item_id: string` + Compression level for the output image. Default: 100. - The unique identifier of the image generation item being processed. + - `output_format: optional "png" or "webp" or "jpeg"` - - `output_index: number` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The index of the output item in the response's output array. + - `"png"` - - `partial_image_b64: string` + - `"webp"` - Base64-encoded partial image data, suitable for rendering as an image. + - `"jpeg"` - - `partial_image_index: number` + - `partial_images: optional number` - 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `sequence_number: number` + - `quality: optional "low" or "medium" or "high" or "auto"` - The sequence number of the image generation item being processed. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `type: "response.image_generation_call.partial_image"` + - `"low"` - The type of the event. Always 'response.image_generation_call.partial_image'. + - `"medium"` - - `"response.image_generation_call.partial_image"` + - `"high"` - - `agent: optional object { agent_name }` + - `"auto"` - The agent that owns this multi-agent streaming event. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `agent_name: string` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - The canonical name of the agent that produced this item. + - `string` - - `BetaResponseMcpCallArgumentsDeltaEvent object { delta, item_id, output_index, 3 more }` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - Emitted when there is a delta (partial update) to the arguments of an MCP 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`. - - `delta: string` + - `"1024x1024"` - A JSON string containing the partial update to the arguments for the MCP tool call. + - `"1024x1536"` - - `item_id: string` + - `"1536x1024"` - The unique identifier of the MCP tool call item being processed. + - `"auto"` - - `output_index: number` + - `LocalShell object { type }` - The index of the output item in the response's output array. + A tool that allows the model to execute shell commands in a local environment. - - `sequence_number: number` + - `type: "local_shell"` - The sequence number of this event. + The type of the local shell tool. Always `local_shell`. - - `type: "response.mcp_call_arguments.delta"` + - `"local_shell"` - The type of the event. Always 'response.mcp_call_arguments.delta'. + - `Shell object { type, allowed_callers, environment }` - - `"response.mcp_call_arguments.delta"` + A tool that allows the model to execute shell commands. - - `agent: optional object { agent_name }` + - `type: "shell"` - The agent that owns this multi-agent streaming event. + The type of the shell tool. Always `shell`. - - `agent_name: string` + - `"shell"` - The canonical name of the agent that produced this item. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `BetaResponseMcpCallArgumentsDoneEvent object { arguments, item_id, output_index, 3 more }` + The tool invocation context(s). - Emitted when the arguments for an MCP tool call are finalized. + - `"direct"` - - `arguments: string` + - `"programmatic"` - A JSON string containing the finalized arguments for the MCP tool call. + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `item_id: string` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - The unique identifier of the MCP tool call item being processed. + - `BetaLocalEnvironment object { type, skills }` - - `output_index: number` + - `BetaContainerReference object { container_id, type }` - The index of the output item in the response's output array. + - `Custom object { name, type, allowed_callers, 3 more }` - - `sequence_number: number` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - The sequence number of this event. + - `name: string` - - `type: "response.mcp_call_arguments.done"` + The name of the custom tool, used to identify it in tool calls. - The type of the event. Always 'response.mcp_call_arguments.done'. + - `type: "custom"` - - `"response.mcp_call_arguments.done"` + The type of the custom tool. Always `custom`. - - `agent: optional object { agent_name }` + - `"custom"` - The agent that owns this multi-agent streaming event. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `agent_name: string` + The tool invocation context(s). - The canonical name of the agent that produced this item. + - `"direct"` - - `BetaResponseMcpCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` + - `"programmatic"` - Emitted when an MCP tool call has completed successfully. + - `defer_loading: optional boolean` - - `item_id: string` + Whether this tool should be deferred and discovered via tool search. - The ID of the MCP tool call item that completed. + - `description: optional string` - - `output_index: number` + Optional description of the custom tool, used to provide more context. - The index of the output item that completed. + - `format: optional object { type } or object { definition, syntax, type }` - - `sequence_number: number` + The input format for the custom tool. Default is unconstrained text. - The sequence number of this event. + - `Text object { type }` - - `type: "response.mcp_call.completed"` + Unconstrained free-form text. - The type of the event. Always 'response.mcp_call.completed'. + - `type: "text"` - - `"response.mcp_call.completed"` + Unconstrained text format. Always `text`. - - `agent: optional object { agent_name }` + - `"text"` - The agent that owns this multi-agent streaming event. + - `Grammar object { definition, syntax, type }` - - `agent_name: string` + A grammar defined by the user. - The canonical name of the agent that produced this item. + - `definition: string` - - `BetaResponseMcpCallFailedEvent object { item_id, output_index, sequence_number, 2 more }` + The grammar definition. - Emitted when an MCP tool call has failed. + - `syntax: "lark" or "regex"` - - `item_id: string` + The syntax of the grammar definition. One of `lark` or `regex`. - The ID of the MCP tool call item that failed. + - `"lark"` - - `output_index: number` + - `"regex"` - The index of the output item that failed. + - `type: "grammar"` - - `sequence_number: number` + Grammar format. Always `grammar`. - The sequence number of this event. + - `"grammar"` - - `type: "response.mcp_call.failed"` + - `Namespace object { description, name, tools, type }` - The type of the event. Always 'response.mcp_call.failed'. + Groups function/custom tools under a shared namespace. - - `"response.mcp_call.failed"` + - `description: string` - - `agent: optional object { agent_name }` + A description of the namespace shown to the model. - The agent that owns this multi-agent streaming event. + - `name: string` - - `agent_name: string` + The namespace name used in tool calls (for example, `crm`). - The canonical name of the agent that produced this item. + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `BetaResponseMcpCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + The function/custom tools available inside this namespace. - Emitted when an MCP tool call is in progress. + - `Function object { name, type, allowed_callers, 5 more }` - - `item_id: string` + - `name: string` - The unique identifier of the MCP tool call item being processed. + - `type: "function"` - - `output_index: number` + - `"function"` - The index of the output item in the response's output array. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `sequence_number: number` + The tool invocation context(s). - The sequence number of this event. + - `"direct"` - - `type: "response.mcp_call.in_progress"` + - `"programmatic"` - The type of the event. Always 'response.mcp_call.in_progress'. + - `defer_loading: optional boolean` - - `"response.mcp_call.in_progress"` + Whether this function should be deferred and discovered via tool search. - - `agent: optional object { agent_name }` + - `description: optional string` - The agent that owns this multi-agent streaming event. + - `output_schema: optional map[unknown]` - - `agent_name: string` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - The canonical name of the agent that produced this item. + - `parameters: optional unknown` - - `BetaResponseMcpListToolsCompletedEvent object { item_id, output_index, sequence_number, 2 more }` + - `strict: optional boolean` - Emitted when the list of available MCP tools has been successfully retrieved. + 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. - - `item_id: string` + - `Custom object { name, type, allowed_callers, 3 more }` - The ID of the MCP tool call item that produced this output. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `output_index: number` + - `name: string` - The index of the output item that was processed. + The name of the custom tool, used to identify it in tool calls. - - `sequence_number: number` + - `type: "custom"` - The sequence number of this event. + The type of the custom tool. Always `custom`. - - `type: "response.mcp_list_tools.completed"` + - `"custom"` - The type of the event. Always 'response.mcp_list_tools.completed'. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"response.mcp_list_tools.completed"` + The tool invocation context(s). - - `agent: optional object { agent_name }` + - `"direct"` - The agent that owns this multi-agent streaming event. + - `"programmatic"` - - `agent_name: string` + - `defer_loading: optional boolean` - The canonical name of the agent that produced this item. + Whether this tool should be deferred and discovered via tool search. - - `BetaResponseMcpListToolsFailedEvent object { item_id, output_index, sequence_number, 2 more }` + - `description: optional string` - Emitted when the attempt to list available MCP tools has failed. + Optional description of the custom tool, used to provide more context. - - `item_id: string` + - `format: optional object { type } or object { definition, syntax, type }` - The ID of the MCP tool call item that failed. + The input format for the custom tool. Default is unconstrained text. - - `output_index: number` + - `Text object { type }` - The index of the output item that failed. + Unconstrained free-form text. - - `sequence_number: number` + - `type: "text"` - The sequence number of this event. + Unconstrained text format. Always `text`. - - `type: "response.mcp_list_tools.failed"` + - `"text"` - The type of the event. Always 'response.mcp_list_tools.failed'. + - `Grammar object { definition, syntax, type }` - - `"response.mcp_list_tools.failed"` + A grammar defined by the user. - - `agent: optional object { agent_name }` + - `definition: string` - The agent that owns this multi-agent streaming event. + The grammar definition. - - `agent_name: string` + - `syntax: "lark" or "regex"` - The canonical name of the agent that produced this item. + The syntax of the grammar definition. One of `lark` or `regex`. - - `BetaResponseMcpListToolsInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + - `"lark"` - Emitted when the system is in the process of retrieving the list of available MCP tools. + - `"regex"` - - `item_id: string` + - `type: "grammar"` - The ID of the MCP tool call item that is being processed. + Grammar format. Always `grammar`. - - `output_index: number` + - `"grammar"` - The index of the output item that is being processed. + - `type: "namespace"` - - `sequence_number: number` + The type of the tool. Always `namespace`. - The sequence number of this event. + - `"namespace"` - - `type: "response.mcp_list_tools.in_progress"` + - `ToolSearch object { type, description, execution, parameters }` - The type of the event. Always 'response.mcp_list_tools.in_progress'. + Hosted or BYOT tool search configuration for deferred tools. - - `"response.mcp_list_tools.in_progress"` + - `type: "tool_search"` - - `agent: optional object { agent_name }` + The type of the tool. Always `tool_search`. - The agent that owns this multi-agent streaming event. + - `"tool_search"` - - `agent_name: string` + - `description: optional string` - The canonical name of the agent that produced this item. + Description shown to the model for a client-executed tool search tool. - - `BetaResponseOutputTextAnnotationAddedEvent object { annotation, annotation_index, content_index, 5 more }` + - `execution: optional "server" or "client"` - Emitted when an annotation is added to output text content. + Whether tool search is executed by the server or by the client. - - `annotation: unknown` + - `"server"` - The annotation object being added. (See annotation schema for details.) + - `"client"` - - `annotation_index: number` + - `parameters: optional unknown` - The index of the annotation within the content part. + Parameter schema for a client-executed tool search tool. - - `content_index: number` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - The index of the content part within the output item. + 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). - - `item_id: string` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - The unique identifier of the item to which the annotation is being added. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `output_index: number` + - `"web_search_preview"` - The index of the output item in the response's output array. + - `"web_search_preview_2025_03_11"` - - `sequence_number: number` + - `search_content_types: optional array of "text" or "image"` - The sequence number of this event. + - `"text"` - - `type: "response.output_text.annotation.added"` + - `"image"` - The type of the event. Always 'response.output_text.annotation.added'. + - `search_context_size: optional "low" or "medium" or "high"` - - `"response.output_text.annotation.added"` + 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. - - `agent: optional object { agent_name }` + - `"low"` - The agent that owns this multi-agent streaming event. + - `"medium"` - - `agent_name: string` + - `"high"` - The canonical name of the agent that produced this item. + - `user_location: optional object { type, city, country, 2 more }` - - `BetaResponseQueuedEvent object { response, sequence_number, type, agent }` + The user's location. - Emitted when a response is queued and waiting to be processed. + - `type: "approximate"` - - `response: BetaResponse` + The type of location approximation. Always `approximate`. - The full response object that is queued. + - `"approximate"` - - `sequence_number: number` + - `city: optional string` - The sequence number for this event. + Free text input for the city of the user, e.g. `San Francisco`. - - `type: "response.queued"` + - `country: optional string` - The type of the event. Always 'response.queued'. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"response.queued"` + - `region: optional string` - - `agent: optional object { agent_name }` + Free text input for the region of the user, e.g. `California`. - The agent that owns this multi-agent streaming event. + - `timezone: optional string` - - `agent_name: string` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The canonical name of the agent that produced this item. + - `ApplyPatch object { type, allowed_callers }` - - `BetaResponseCustomToolCallInputDeltaEvent object { delta, item_id, output_index, 3 more }` + Allows the assistant to create, delete, or update files using unified diffs. - Event representing a delta (partial update) to the input of a custom tool call. + - `type: "apply_patch"` - - `delta: string` + The type of the tool. Always `apply_patch`. - The incremental input data (delta) for the custom tool call. + - `"apply_patch"` - - `item_id: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - Unique identifier for the API item associated with this event. + The tool invocation context(s). - - `output_index: number` + - `"direct"` - The index of the output this delta applies to. + - `"programmatic"` - - `sequence_number: number` + - `type: "additional_tools"` - The sequence number of this event. + The item type. Always `additional_tools`. - - `type: "response.custom_tool_call_input.delta"` + - `"additional_tools"` - The event type identifier. + - `id: optional string` - - `"response.custom_tool_call_input.delta"` + The unique ID of this additional tools item. - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. - - `BetaResponseCustomToolCallInputDoneEvent object { input, item_id, output_index, 3 more }` + - `Reasoning object { id, summary, type, 4 more }` - Event indicating that input for a custom tool call is complete. + 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). - - `input: string` + - `id: string` - The complete input data for the custom tool call. + The unique identifier of the reasoning content. - - `item_id: string` + - `summary: array of object { text, type }` - Unique identifier for the API item associated with this event. + Reasoning summary content. - - `output_index: number` + - `text: string` - The index of the output this event applies to. + A summary of the reasoning output from the model so far. - - `sequence_number: number` + - `type: "summary_text"` - The sequence number of this event. + The type of the object. Always `summary_text`. - - `type: "response.custom_tool_call_input.done"` + - `"summary_text"` - The event type identifier. + - `type: "reasoning"` - - `"response.custom_tool_call_input.done"` + The type of the object. Always `reasoning`. + + - `"reasoning"` - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. -### Beta Response Text Config - -- `BetaResponseTextConfig object { format, verbosity }` + - `content: optional array of object { text, type }` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + Reasoning text content. - - [Text inputs and outputs](/docs/guides/text) - - [Structured Outputs](/docs/guides/structured-outputs) + - `text: string` - - `format: optional BetaResponseFormatTextConfig` + The reasoning text from the model. - An object specifying the format that the model must output. + - `type: "reasoning_text"` - 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 reasoning text. Always `reasoning_text`. - The default format is `{ "type": "text" }` with no additional options. + - `"reasoning_text"` - **Not recommended for gpt-4o and newer models:** + - `encrypted_content: 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. + 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. - - `Text object { type }` + - `status: optional "in_progress" or "completed" or "incomplete"` - Default response format. Used to generate text responses. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `type: "text"` + - `"in_progress"` - The type of response format being defined. Always `text`. + - `"completed"` - - `"text"` + - `"incomplete"` - - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` + - `Compaction object { encrypted_content, type, id, agent }` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - - `name: string` + - `encrypted_content: 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 encrypted content of the compaction summary. - - `schema: map[unknown]` + - `type: "compaction"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The type of the item. Always `compaction`. - - `type: "json_schema"` + - `"compaction"` - The type of response format being defined. Always `json_schema`. + - `id: optional string` - - `"json_schema"` + The ID of the compaction item. - - `description: optional string` + - `agent: optional object { agent_name }` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The agent that produced this item. - - `strict: optional boolean` + - `agent_name: 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 canonical name of the agent that produced this item. - - `JSONObject object { type }` + - `ImageGenerationCall object { id, result, status, 2 more }` - 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. + An image generation request made by the model. - - `type: "json_object"` + - `id: string` - The type of response format being defined. Always `json_object`. + The unique ID of the image generation call. - - `"json_object"` + - `result: string` - - `verbosity: optional "low" or "medium" or "high"` + The generated image encoded in base64. - 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 "completed" or "generating" or "failed"` - - `"low"` + The status of the image generation call. - - `"medium"` + - `"in_progress"` - - `"high"` + - `"completed"` -### Beta Response Text Delta Event + - `"generating"` -- `BetaResponseTextDeltaEvent object { content_index, delta, item_id, 5 more }` + - `"failed"` - Emitted when there is an additional text delta. + - `type: "image_generation_call"` - - `content_index: number` + The type of the image generation call. Always `image_generation_call`. - The index of the content part that the text delta was added to. + - `"image_generation_call"` - - `delta: string` + - `agent: optional object { agent_name }` - The text delta that was added. + The agent that produced this item. - - `item_id: string` + - `agent_name: string` - The ID of the output item that the text delta was added to. + The canonical name of the agent that produced this item. - - `logprobs: array of object { token, logprob, top_logprobs }` + - `CodeInterpreterCall object { id, code, container_id, 4 more }` - The log probabilities of the tokens in the delta. + A tool call to run code. - - `token: string` + - `id: string` - A possible text token. + The unique ID of the code interpreter tool call. - - `logprob: number` + - `code: string` - The log probability of this token. + The code to run, or null if not available. - - `top_logprobs: optional array of object { token, logprob }` + - `container_id: string` - The log probabilities of up to 20 of the most likely tokens. + The ID of the container used to run the code. - - `token: optional string` + - `outputs: array of object { logs, type } or object { type, url }` - A possible text token. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `logprob: optional number` + - `Logs object { logs, type }` - The log probability of this token. + The logs output from the code interpreter. - - `output_index: number` + - `logs: string` - The index of the output item that the text delta was added to. + The logs output from the code interpreter. - - `sequence_number: number` + - `type: "logs"` - The sequence number for this event. + The type of the output. Always `logs`. - - `type: "response.output_text.delta"` + - `"logs"` - The type of the event. Always `response.output_text.delta`. + - `Image object { type, url }` - - `"response.output_text.delta"` + The image output from the code interpreter. - - `agent: optional object { agent_name }` + - `type: "image"` - The agent that owns this multi-agent streaming event. + The type of the output. Always `image`. - - `agent_name: string` + - `"image"` - The canonical name of the agent that produced this item. + - `url: string` -### Beta Response Text Done Event + The URL of the image output from the code interpreter. -- `BetaResponseTextDoneEvent object { content_index, item_id, logprobs, 5 more }` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - Emitted when text content is finalized. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `content_index: number` + - `"in_progress"` - The index of the content part that the text content is finalized. + - `"completed"` - - `item_id: string` + - `"incomplete"` - The ID of the output item that the text content is finalized. + - `"interpreting"` - - `logprobs: array of object { token, logprob, top_logprobs }` + - `"failed"` - The log probabilities of the tokens in the delta. + - `type: "code_interpreter_call"` - - `token: string` + The type of the code interpreter tool call. Always `code_interpreter_call`. - A possible text token. + - `"code_interpreter_call"` - - `logprob: number` + - `agent: optional object { agent_name }` - The log probability of this token. + The agent that produced this item. - - `top_logprobs: optional array of object { token, logprob }` + - `agent_name: string` - The log probabilities of up to 20 of the most likely tokens. + The canonical name of the agent that produced this item. - - `token: optional string` + - `LocalShellCall object { id, action, call_id, 3 more }` - A possible text token. + A tool call to run a command on the local shell. - - `logprob: optional number` + - `id: string` - The log probability of this token. + The unique ID of the local shell call. - - `output_index: number` + - `action: object { command, env, type, 3 more }` - The index of the output item that the text content is finalized. + Execute a shell command on the server. - - `sequence_number: number` + - `command: array of string` - The sequence number for this event. + The command to run. - - `text: string` + - `env: map[string]` - The text content that is finalized. + Environment variables to set for the command. - - `type: "response.output_text.done"` + - `type: "exec"` - The type of the event. Always `response.output_text.done`. + The type of the local shell action. Always `exec`. - - `"response.output_text.done"` + - `"exec"` - - `agent: optional object { agent_name }` + - `timeout_ms: optional number` - The agent that owns this multi-agent streaming event. + Optional timeout in milliseconds for the command. - - `agent_name: string` + - `user: optional string` - The canonical name of the agent that produced this item. + Optional user to run the command as. -### Beta Response Usage + - `working_directory: optional string` -- `BetaResponseUsage object { input_tokens, input_tokens_details, output_tokens, 2 more }` + Optional working directory to run the command in. - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `call_id: string` - - `input_tokens: number` + The unique ID of the local shell tool call generated by the model. - The number of input tokens. + - `status: "in_progress" or "completed" or "incomplete"` - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + The status of the local shell call. - A detailed breakdown of the input tokens. + - `"in_progress"` - - `cache_write_tokens: number` + - `"completed"` - The number of input tokens that were written to the cache. + - `"incomplete"` - - `cached_tokens: number` + - `type: "local_shell_call"` - The number of tokens that were retrieved from the cache. - [More on prompt caching](/docs/guides/prompt-caching). + The type of the local shell call. Always `local_shell_call`. - - `output_tokens: number` + - `"local_shell_call"` - The number of output tokens. + - `agent: optional object { agent_name }` - - `output_tokens_details: object { reasoning_tokens }` + The agent that produced this item. - A detailed breakdown of the output tokens. + - `agent_name: string` - - `reasoning_tokens: number` + The canonical name of the agent that produced this item. - The number of reasoning tokens. + - `LocalShellCallOutput object { id, output, type, 2 more }` - - `total_tokens: number` + The output of a local shell tool call. - The total number of tokens used. + - `id: string` -### Beta Response Web Search Call Completed Event + The unique ID of the local shell tool call generated by the model. -- `BetaResponseWebSearchCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` + - `output: string` - Emitted when a web search call is completed. + A JSON string of the output of the local shell tool call. - - `item_id: string` + - `type: "local_shell_call_output"` - Unique ID for the output item associated with the web search call. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `output_index: number` + - `"local_shell_call_output"` - The index of the output item that the web search call is associated with. + - `agent: optional object { agent_name }` - - `sequence_number: number` + The agent that produced this item. - The sequence number of the web search call being processed. + - `agent_name: string` - - `type: "response.web_search_call.completed"` + The canonical name of the agent that produced this item. - The type of the event. Always `response.web_search_call.completed`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"response.web_search_call.completed"` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `agent: optional object { agent_name }` + - `"in_progress"` - The agent that owns this multi-agent streaming event. + - `"completed"` - - `agent_name: string` + - `"incomplete"` - The canonical name of the agent that produced this item. + - `ShellCall object { action, call_id, type, 5 more }` -### Beta Response Web Search Call In Progress Event + A tool representing a request to execute one or more shell commands. -- `BetaResponseWebSearchCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + - `action: object { commands, max_output_length, timeout_ms }` - Emitted when a web search call is initiated. + The shell commands and limits that describe how to run the tool call. - - `item_id: string` + - `commands: array of string` - Unique ID for the output item associated with the web search call. + Ordered shell commands for the execution environment to run. - - `output_index: number` + - `max_output_length: optional number` - The index of the output item that the web search call is associated with. + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `sequence_number: number` + - `timeout_ms: optional number` - The sequence number of the web search call being processed. + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `type: "response.web_search_call.in_progress"` + - `call_id: string` - The type of the event. Always `response.web_search_call.in_progress`. + The unique ID of the shell tool call generated by the model. - - `"response.web_search_call.in_progress"` + - `type: "shell_call"` - - `agent: optional object { agent_name }` + The type of the item. Always `shell_call`. - The agent that owns this multi-agent streaming event. + - `"shell_call"` - - `agent_name: string` + - `id: optional string` - The canonical name of the agent that produced this item. + The unique ID of the shell tool call. Populated when this item is returned via API. -### Beta Response Web Search Call Searching Event + - `agent: optional object { agent_name }` -- `BetaResponseWebSearchCallSearchingEvent object { item_id, output_index, sequence_number, 2 more }` + The agent that produced this item. - Emitted when a web search call is executing. + - `agent_name: string` - - `item_id: string` + The canonical name of the agent that produced this item. - Unique ID for the output item associated with the web search call. + - `caller: optional object { type } or object { caller_id, type }` - - `output_index: number` + The execution context that produced this tool call. - The index of the output item that the web search call is associated with. + - `Direct object { type }` - - `sequence_number: number` + - `type: "direct"` - The sequence number of the web search call being processed. + The caller type. Always `direct`. - - `type: "response.web_search_call.searching"` + - `"direct"` - The type of the event. Always `response.web_search_call.searching`. + - `Program object { caller_id, type }` - - `"response.web_search_call.searching"` + - `caller_id: string` - - `agent: optional object { agent_name }` + The call ID of the program item that produced this tool call. - The agent that owns this multi-agent streaming event. + - `type: "program"` - - `agent_name: string` + The caller type. Always `program`. - The canonical name of the agent that produced this item. + - `"program"` -### Beta Responses Client Event + - `environment: optional BetaLocalEnvironment or BetaContainerReference` -- `BetaResponsesClientEvent = object { type, background, context_management, 30 more } or BetaResponseInjectEvent` + The environment to execute the shell commands in. - Client events accepted by the Responses WebSocket server. + - `BetaLocalEnvironment object { type, skills }` - - `ResponseCreate object { type, background, context_management, 30 more }` + - `BetaContainerReference object { container_id, type }` - Client event for creating a response over a persistent WebSocket connection. - This payload uses the same top-level fields as `POST /v1/responses`. + - `status: optional "in_progress" or "completed" or "incomplete"` - Notes: + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `stream` is implicit over WebSocket and should not be sent. - - `background` is not supported over WebSocket. + - `"in_progress"` - - `type: "response.create"` + - `"completed"` - The type of the client event. Always `response.create`. + - `"incomplete"` - - `"response.create"` + - `ShellCallOutput object { call_id, output, type, 5 more }` - - `background: optional boolean` + The streamed output items emitted by a shell tool call. - Whether to run the model response in the background. - [Learn more](/docs/guides/background). + - `call_id: string` - - `context_management: optional array of object { type, compact_threshold }` + The unique ID of the shell tool call generated by the model. - Context management configuration for this request. + - `output: array of BetaResponseFunctionShellCallOutputContent` - - `type: string` + Captured chunks of stdout and stderr output, along with their associated outcomes. - The context management entry type. Currently only 'compaction' is supported. + - `outcome: object { type } or object { exit_code, type }` - - `compact_threshold: optional number` + The exit or timeout outcome associated with this shell call. - Token threshold at which compaction should be triggered for this entry. + - `Timeout object { type }` - - `conversation: optional string or BetaResponseConversationParam` + Indicates that the shell call exceeded its configured time limit. - 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. + - `type: "timeout"` - - `ConversationID = string` + The outcome type. Always `timeout`. - The unique ID of the conversation. + - `"timeout"` - - `BetaResponseConversationParam object { id }` + - `Exit object { exit_code, type }` - The conversation that this response belongs to. + Indicates that the shell commands finished and returned an exit code. - - `id: string` + - `exit_code: number` - The unique ID of the conversation. + The exit code returned by the shell process. - - `include: optional array of BetaResponseIncludable` + - `type: "exit"` - Specify additional output data to include in the model response. Currently supported values are: + The outcome type. Always `exit`. - - `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). + - `"exit"` - - `"file_search_call.results"` + - `stderr: string` - - `"web_search_call.results"` + Captured stderr output for the shell call. - - `"web_search_call.action.sources"` + - `stdout: string` - - `"message.input_image.image_url"` + Captured stdout output for the shell call. - - `"computer_call_output.output.image_url"` + - `type: "shell_call_output"` - - `"code_interpreter_call.outputs"` + The type of the item. Always `shell_call_output`. - - `"reasoning.encrypted_content"` + - `"shell_call_output"` - - `"message.output_text.logprobs"` + - `id: optional string` - - `input: optional string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + The unique ID of the shell tool call output. Populated when this item is returned via API. - Text, image, or file inputs to the model, used to generate a response. + - `agent: optional object { agent_name }` - Learn more: + The agent that produced this item. - - [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) + - `agent_name: string` - - `TextInput = string` + The canonical name of the agent that produced this item. - A text input to the model, equivalent to a text input with the - `user` role. + - `caller: optional object { type } or object { caller_id, type }` - - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + The execution context that produced this tool call. - A list of one or many input items to the model, containing - different content types. + - `Direct object { type }` - - `BetaEasyInputMessage object { content, role, phase, type }` + - `type: "direct"` - 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 caller type. Always `direct`. - - `content: string or BetaResponseInputMessageContentList` + - `"direct"` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + - `Program object { caller_id, type }` - - `TextInput = string` + - `caller_id: string` - A text input to the model. + The call ID of the program item that produced this tool call. - - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` + - `type: "program"` - A list of one or many input items to the model, containing different content - types. + The caller type. Always `program`. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `"program"` - A text input to the model. + - `max_output_length: optional number` - - `text: string` + The maximum number of UTF-8 characters captured for this shell call's combined output. - The text input to the model. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `type: "input_text"` + The status of the shell call output. - The type of the input item. Always `input_text`. + - `"in_progress"` - - `"input_text"` + - `"completed"` - - `prompt_cache_breakpoint: optional object { mode }` + - `"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. + - `ApplyPatchCall object { call_id, operation, status, 4 more }` - - `mode: "explicit"` + A tool call representing a request to create, delete, or update files using diff patches. - The breakpoint mode. Always `explicit`. + - `call_id: string` - - `"explicit"` + The unique ID of the apply patch tool call generated by the model. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + The specific create, delete, or update instruction for the apply_patch tool call. - - `detail: "low" or "high" or "auto" or "original"` + - `CreateFile object { diff, path, type }` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Instruction for creating a new file via the apply_patch tool. - - `"low"` + - `diff: string` - - `"high"` + Unified diff content to apply when creating the file. - - `"auto"` + - `path: string` - - `"original"` + Path of the file to create relative to the workspace root. - - `type: "input_image"` + - `type: "create_file"` - The type of the input item. Always `input_image`. + The operation type. Always `create_file`. - - `"input_image"` + - `"create_file"` - - `file_id: optional string` + - `DeleteFile object { path, type }` - The ID of the file to be sent to the model. + Instruction for deleting an existing file via the apply_patch tool. - - `image_url: optional string` + - `path: string` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + Path of the file to delete relative to the workspace root. - - `prompt_cache_breakpoint: optional object { mode }` + - `type: "delete_file"` - 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 operation type. Always `delete_file`. - - `mode: "explicit"` + - `"delete_file"` - The breakpoint mode. Always `explicit`. + - `UpdateFile object { diff, path, type }` - - `"explicit"` + Instruction for updating an existing file via the apply_patch tool. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `diff: string` - A file input to the model. + Unified diff content to apply to the existing file. - - `type: "input_file"` + - `path: string` - The type of the input item. Always `input_file`. + Path of the file to update relative to the workspace root. - - `"input_file"` + - `type: "update_file"` - - `detail: optional "auto" or "low" or "high"` + The operation type. Always `update_file`. - 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`. + - `"update_file"` - - `"auto"` + - `status: "in_progress" or "completed"` - - `"low"` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `"high"` + - `"in_progress"` - - `file_data: optional string` + - `"completed"` - The content of the file to be sent to the model. + - `type: "apply_patch_call"` - - `file_id: optional string` + The type of the item. Always `apply_patch_call`. - The ID of the file to be sent to the model. + - `"apply_patch_call"` - - `file_url: optional string` + - `id: optional string` - The URL of the file to be sent to the model. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `filename: optional string` + - `agent: optional object { agent_name }` - The name of the file to be sent to the model. + The agent that produced this item. - - `prompt_cache_breakpoint: optional object { mode }` + - `agent_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 canonical name of the agent that produced this item. - - `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 }` - - `role: "user" or "assistant" or "system" or "developer"` + - `type: "direct"` - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + The caller type. Always `direct`. - - `"user"` + - `"direct"` - - `"assistant"` + - `Program object { caller_id, type }` - - `"system"` + - `caller_id: string` - - `"developer"` + The call ID of the program item that produced this tool call. - - `phase: optional "commentary" or "final_answer"` + - `type: "program"` - 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 caller type. Always `program`. - - `"commentary"` + - `"program"` - - `"final_answer"` + - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` - - `type: optional "message"` + The streamed output emitted by an apply patch tool call. - The type of the message input. Always `message`. + - `call_id: string` - - `"message"` + The unique ID of the apply patch tool call generated by the model. - - `Message object { content, role, agent, 2 more }` + - `status: "completed" or "failed"` - 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. + The status of the apply patch tool call output. One of `completed` or `failed`. - - `content: BetaResponseInputMessageContentList` + - `"completed"` - A list of one or many input items to the model, containing different content - types. + - `"failed"` - - `role: "user" or "system" or "developer"` + - `type: "apply_patch_call_output"` - The role of the message input. One of `user`, `system`, or `developer`. + The type of the item. Always `apply_patch_call_output`. - - `"user"` + - `"apply_patch_call_output"` - - `"system"` + - `id: optional string` - - `"developer"` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - `agent: optional object { agent_name }` @@ -171774,253 +171436,255 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `caller: optional object { type } or object { caller_id, type }` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The execution context that produced this tool call. - - `"in_progress"` + - `Direct object { type }` - - `"completed"` + - `type: "direct"` - - `"incomplete"` + The caller type. Always `direct`. - - `type: optional "message"` + - `"direct"` - The type of the message input. Always set to `message`. + - `Program object { caller_id, type }` - - `"message"` + - `caller_id: string` - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + The call ID of the program item that produced this tool call. - An output message from the model. + - `type: "program"` - - `id: string` + The caller type. Always `program`. - The unique ID of the output message. + - `"program"` - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `output: optional string` - The content of the output message. + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - `BetaResponseOutputText object { annotations, logprobs, text, type }` + - `McpListTools object { id, server_label, tools, 3 more }` - A text output from the model. + A list of tools available on an MCP server. - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + - `id: string` - The annotations of the text output. + The unique ID of the list. - - `FileCitation object { file_id, filename, index, type }` + - `server_label: string` - A citation to a file. + The label of the MCP server. - - `file_id: string` + - `tools: array of object { input_schema, name, annotations, description }` - The ID of the file. + The tools available on the server. - - `filename: string` + - `input_schema: unknown` - The filename of the file cited. + The JSON schema describing the tool's input. - - `index: number` + - `name: string` - The index of the file in the list of files. + The name of the tool. - - `type: "file_citation"` + - `annotations: optional unknown` - The type of the file citation. Always `file_citation`. + Additional annotations about the tool. - - `"file_citation"` + - `description: optional string` - - `URLCitation object { end_index, start_index, title, 2 more }` + The description of the tool. - A citation for a web resource used to generate a model response. + - `type: "mcp_list_tools"` - - `end_index: number` + The type of the item. Always `mcp_list_tools`. - The index of the last character of the URL citation in the message. + - `"mcp_list_tools"` - - `start_index: number` + - `agent: optional object { agent_name }` - The index of the first character of the URL citation in the message. + The agent that produced this item. - - `title: string` + - `agent_name: string` - The title of the web resource. + The canonical name of the agent that produced this item. - - `type: "url_citation"` + - `error: optional string` - The type of the URL citation. Always `url_citation`. + Error message if the server could not list tools. - - `"url_citation"` + - `McpApprovalRequest object { id, arguments, name, 3 more }` - - `url: string` + A request for human approval of a tool invocation. - The URL of the web resource. + - `id: string` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + The unique ID of the approval request. - A citation for a container file used to generate a model response. + - `arguments: string` - - `container_id: string` + A JSON string of arguments for the tool. - The ID of the container file. + - `name: string` - - `end_index: number` + The name of the tool to run. - The index of the last character of the container file citation in the message. + - `server_label: string` - - `file_id: string` + The label of the MCP server making the request. - The ID of the file. + - `type: "mcp_approval_request"` - - `filename: string` + The type of the item. Always `mcp_approval_request`. - The filename of the container file cited. + - `"mcp_approval_request"` - - `start_index: number` + - `agent: optional object { agent_name }` - The index of the first character of the container file citation in the message. + The agent that produced this item. - - `type: "container_file_citation"` + - `agent_name: string` - The type of the container file citation. Always `container_file_citation`. + The canonical name of the agent that produced this item. - - `"container_file_citation"` + - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` - - `FilePath object { file_id, index, type }` + A response to an MCP approval request. - A path to a file. + - `approval_request_id: string` - - `file_id: string` + The ID of the approval request being answered. - The ID of the file. + - `approve: boolean` - - `index: number` + Whether the request was approved. - The index of the file in the list of files. + - `type: "mcp_approval_response"` - - `type: "file_path"` + The type of the item. Always `mcp_approval_response`. - The type of the file path. Always `file_path`. + - `"mcp_approval_response"` - - `"file_path"` + - `id: optional string` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + The unique ID of the approval response - - `token: string` + - `agent: optional object { agent_name }` - - `bytes: array of number` + The agent that produced this item. - - `logprob: number` + - `agent_name: string` - - `top_logprobs: array of object { token, bytes, logprob }` + The canonical name of the agent that produced this item. - - `token: string` + - `reason: optional string` - - `bytes: array of number` + Optional reason for the decision. - - `logprob: number` + - `McpCall object { id, arguments, name, 7 more }` - - `text: string` + An invocation of a tool on an MCP server. - The text output from the model. + - `id: string` - - `type: "output_text"` + The unique ID of the tool call. - The type of the output text. Always `output_text`. + - `arguments: string` - - `"output_text"` + A JSON string of the arguments passed to the tool. - - `BetaResponseOutputRefusal object { refusal, type }` + - `name: string` - A refusal from the model. + The name of the tool that was run. - - `refusal: string` + - `server_label: string` - The refusal explanation from the model. + The label of the MCP server running the tool. - - `type: "refusal"` + - `type: "mcp_call"` - The type of the refusal. Always `refusal`. + The type of the item. Always `mcp_call`. - - `"refusal"` + - `"mcp_call"` - - `role: "assistant"` + - `agent: optional object { agent_name }` - The role of the output message. Always `assistant`. + The agent that produced this item. - - `"assistant"` + - `agent_name: string` - - `status: "in_progress" or "completed" or "incomplete"` + The canonical name of the agent that produced this item. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `approval_request_id: optional string` - - `"in_progress"` + 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. - - `"completed"` + - `error: optional string` - - `"incomplete"` + The error from the tool call, if any. - - `type: "message"` + - `output: optional string` - The type of the output message. Always `message`. + The output from the tool call. - - `"message"` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `agent: optional object { agent_name }` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - The agent that produced this item. + - `"in_progress"` - - `agent_name: string` + - `"completed"` - The canonical name of the agent that produced this item. + - `"incomplete"` - - `phase: optional "commentary" or "final_answer"` + - `"calling"` - 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. + - `"failed"` - - `"commentary"` + - `CustomToolCallOutput object { call_id, output, type, 3 more }` - - `"final_answer"` + The output of a custom tool call from your code, being sent back to the model. - - `FileSearchCall object { id, queries, status, 3 more }` + - `call_id: string` - The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + The call ID, used to map this custom tool call output to a custom tool call. - - `id: string` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The unique ID of the file search tool call. + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `queries: array of string` + - `StringOutput = string` - The queries used to search for files. + A string of the output of the custom tool call. - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + Text, image, or file output of the custom tool call. - - `"in_progress"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `"searching"` + A text input to the model. - - `"completed"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `"incomplete"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"failed"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `type: "file_search_call"` + A file input to the model. - The type of the file search tool call. Always `file_search_call`. + - `type: "custom_tool_call_output"` - - `"file_search_call"` + 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. - `agent: optional object { agent_name }` @@ -172030,504 +171694,507 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `results: optional array of object { attributes, file_id, filename, 2 more }` - - The results of the file search tool call. + - `caller: optional object { type } or object { caller_id, type }` - - `attributes: optional map[string or number or boolean]` + The execution context that produced this tool call. - 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. + - `Direct object { type }` - - `string` + - `type: "direct"` - - `number` + The caller type. Always `direct`. - - `boolean` + - `"direct"` - - `file_id: optional string` + - `Program object { caller_id, type }` - The unique ID of the file. + - `caller_id: string` - - `filename: optional string` + The call ID of the program item that produced this tool call. - The name of the file. + - `type: "program"` - - `score: optional number` + The caller type. Always `program`. - The relevance score of the file - a value between 0 and 1. + - `"program"` - - `text: optional string` + - `CustomToolCall object { call_id, input, name, 5 more }` - The text that was retrieved from the file. + A call to a custom tool created by the model. - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + - `call_id: string` - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + An identifier used to map this custom tool call to a tool call output. - - `id: string` + - `input: string` - The unique ID of the computer call. + The input for the custom tool call generated by the model. - - `call_id: string` + - `name: string` - An identifier used when responding to the tool call with output. + The name of the custom tool being called. - - `pending_safety_checks: array of object { id, code, message }` + - `type: "custom_tool_call"` - The pending safety checks for the computer call. + The type of the custom tool call. Always `custom_tool_call`. - - `id: string` + - `"custom_tool_call"` - The ID of the pending safety check. + - `id: optional string` - - `code: optional string` + The unique ID of the custom tool call in the OpenAI platform. - The type of the pending safety check. + - `agent: optional object { agent_name }` - - `message: optional string` + The agent that produced this item. - Details about the pending safety check. + - `agent_name: string` - - `status: "in_progress" or "completed" or "incomplete"` + The canonical name of the agent that produced this item. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `caller: optional object { type } or object { caller_id, type }` - - `"in_progress"` + The execution context that produced this tool call. - - `"completed"` + - `Direct object { type }` - - `"incomplete"` + - `type: "direct"` - - `type: "computer_call"` + - `"direct"` - The type of the computer call. Always `computer_call`. + - `Program object { caller_id, type }` - - `"computer_call"` + - `caller_id: string` - - `action: optional BetaComputerAction` + The call ID of the program item that produced this tool call. - A click action. + - `type: "program"` - - `Click object { button, type, x, 2 more }` + - `"program"` - A click action. + - `namespace: optional string` - - `button: "left" or "right" or "wheel" or 2 more` + The namespace of the custom tool being called. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `CompactionTrigger object { type, agent }` - - `"left"` + Compacts the current context. Must be the final input item. - - `"right"` + - `type: "compaction_trigger"` - - `"wheel"` + The type of the item. Always `compaction_trigger`. - - `"back"` + - `"compaction_trigger"` - - `"forward"` + - `agent: optional object { agent_name }` - - `type: "click"` + The agent that produced this item. - Specifies the event type. For a click action, this property is always `click`. + - `agent_name: string` - - `"click"` + The canonical name of the agent that produced this item. - - `x: number` + - `ItemReference object { id, agent, type }` - The x-coordinate where the click occurred. + An internal identifier for an item to reference. - - `y: number` + - `id: string` - The y-coordinate where the click occurred. + The ID of the item to reference. - - `keys: optional array of string` + - `agent: optional object { agent_name }` - The keys being held while clicking. + The agent that produced this item. - - `DoubleClick object { keys, type, x, y }` + - `agent_name: string` - A double click action. + The canonical name of the agent that produced this item. - - `keys: array of string` + - `type: optional "item_reference"` - The keys being held while double-clicking. + The type of item to reference. Always `item_reference`. - - `type: "double_click"` + - `"item_reference"` - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `Program object { id, call_id, code, 3 more }` - - `"double_click"` + - `id: string` - - `x: number` + The unique ID of this program item. - The x-coordinate where the double click occurred. + - `call_id: string` - - `y: number` + The stable call ID of the program item. - The y-coordinate where the double click occurred. + - `code: string` - - `Drag object { path, type, keys }` + The JavaScript source executed by programmatic tool calling. - A drag action. + - `fingerprint: string` - - `path: array of object { x, y }` + Opaque program replay fingerprint that must be round-tripped. - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `type: "program"` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + The item type. Always `program`. - - `x: number` + - `"program"` - The x-coordinate. + - `agent: optional object { agent_name }` - - `y: number` + The agent that produced this item. - The y-coordinate. + - `agent_name: string` - - `type: "drag"` + The canonical name of the agent that produced this item. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `ProgramOutput object { id, call_id, result, 3 more }` - - `"drag"` + - `id: string` - - `keys: optional array of string` + The unique ID of this program output item. - The keys being held while dragging the mouse. + - `call_id: string` - - `Keypress object { keys, type }` + The call ID of the program item. - A collection of keypresses the model would like to perform. + - `result: string` - - `keys: array of string` + The result produced by the program item. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `status: "completed" or "incomplete"` - - `type: "keypress"` + The terminal status of the program output. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `"completed"` - - `"keypress"` + - `"incomplete"` - - `Move object { type, x, y, keys }` + - `type: "program_output"` - A mouse move action. + The item type. Always `program_output`. - - `type: "move"` + - `"program_output"` - Specifies the event type. For a move action, this property is always set to `move`. + - `agent: optional object { agent_name }` - - `"move"` + The agent that produced this item. - - `x: number` + - `agent_name: string` - The x-coordinate to move to. + The canonical name of the agent that produced this item. - - `y: number` + - `metadata: map[string]` - The y-coordinate to move to. + 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: optional array of string` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The keys being held while moving the mouse. + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - - `Screenshot object { type }` + 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. - A screenshot action. + - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` - - `type: "screenshot"` + 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. - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `"gpt-5.6-sol"` - - `"screenshot"` + - `"gpt-5.6-terra"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `"gpt-5.6-luna"` - A scroll action. + - `"gpt-5.4"` - - `scroll_x: number` + - `"gpt-5.4-mini"` - The horizontal scroll distance. + - `"gpt-5.4-nano"` - - `scroll_y: number` + - `"gpt-5.4-mini-2026-03-17"` - The vertical scroll distance. + - `"gpt-5.4-nano-2026-03-17"` - - `type: "scroll"` + - `"gpt-5.3-chat-latest"` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `"gpt-5.2"` - - `"scroll"` + - `"gpt-5.2-2025-12-11"` - - `x: number` + - `"gpt-5.2-chat-latest"` - The x-coordinate where the scroll occurred. + - `"gpt-5.2-pro"` - - `y: number` + - `"gpt-5.2-pro-2025-12-11"` - The y-coordinate where the scroll occurred. + - `"gpt-5.1"` - - `keys: optional array of string` + - `"gpt-5.1-2025-11-13"` - The keys being held while scrolling. + - `"gpt-5.1-codex"` - - `Type object { text, type }` + - `"gpt-5.1-mini"` - An action to type in text. + - `"gpt-5.1-chat-latest"` - - `text: string` + - `"gpt-5"` - The text to type. + - `"gpt-5-mini"` - - `type: "type"` + - `"gpt-5-nano"` - Specifies the event type. For a type action, this property is always set to `type`. + - `"gpt-5-2025-08-07"` - - `"type"` + - `"gpt-5-mini-2025-08-07"` - - `Wait object { type }` + - `"gpt-5-nano-2025-08-07"` - A wait action. + - `"gpt-5-chat-latest"` - - `type: "wait"` + - `"gpt-4.1"` - Specifies the event type. For a wait action, this property is always set to `wait`. + - `"gpt-4.1-mini"` - - `"wait"` + - `"gpt-4.1-nano"` - - `actions: optional BetaComputerActionList` + - `"gpt-4.1-2025-04-14"` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `"gpt-4.1-mini-2025-04-14"` - - `Click object { button, type, x, 2 more }` + - `"gpt-4.1-nano-2025-04-14"` - A click action. + - `"o4-mini"` - - `DoubleClick object { keys, type, x, y }` + - `"o4-mini-2025-04-16"` - A double click action. + - `"o3"` - - `Drag object { path, type, keys }` + - `"o3-2025-04-16"` - A drag action. + - `"o3-mini"` - - `Keypress object { keys, type }` + - `"o3-mini-2025-01-31"` - A collection of keypresses the model would like to perform. + - `"o1"` - - `Move object { type, x, y, keys }` + - `"o1-2024-12-17"` - A mouse move action. + - `"o1-preview"` - - `Screenshot object { type }` + - `"o1-preview-2024-09-12"` - A screenshot action. + - `"o1-mini"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `"o1-mini-2024-09-12"` - A scroll action. + - `"gpt-4o"` - - `Type object { text, type }` + - `"gpt-4o-2024-11-20"` - An action to type in text. + - `"gpt-4o-2024-08-06"` - - `Wait object { type }` + - `"gpt-4o-2024-05-13"` - A wait action. + - `"gpt-4o-audio-preview"` - - `agent: optional object { agent_name }` + - `"gpt-4o-audio-preview-2024-10-01"` - The agent that produced this item. + - `"gpt-4o-audio-preview-2024-12-17"` - - `agent_name: string` + - `"gpt-4o-audio-preview-2025-06-03"` - The canonical name of the agent that produced this item. + - `"gpt-4o-mini-audio-preview"` - - `ComputerCallOutput object { call_id, output, type, 4 more }` + - `"gpt-4o-mini-audio-preview-2024-12-17"` - The output of a computer tool call. + - `"gpt-4o-search-preview"` - - `call_id: string` + - `"gpt-4o-mini-search-preview"` - The ID of the computer tool call that produced the output. + - `"gpt-4o-search-preview-2025-03-11"` - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `"gpt-4o-mini-search-preview-2025-03-11"` - A computer screenshot image used with the computer use tool. + - `"chatgpt-4o-latest"` - - `type: "computer_screenshot"` + - `"codex-mini-latest"` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `"gpt-4o-mini"` - - `"computer_screenshot"` + - `"gpt-4o-mini-2024-07-18"` - - `file_id: optional string` + - `"gpt-4-turbo"` - The identifier of an uploaded file that contains the screenshot. + - `"gpt-4-turbo-2024-04-09"` - - `image_url: optional string` + - `"gpt-4-0125-preview"` - The URL of the screenshot image. + - `"gpt-4-turbo-preview"` - - `type: "computer_call_output"` + - `"gpt-4-1106-preview"` - The type of the computer tool call output. Always `computer_call_output`. + - `"gpt-4-vision-preview"` - - `"computer_call_output"` + - `"gpt-4"` - - `id: optional string` + - `"gpt-4-0314"` - The ID of the computer tool call output. + - `"gpt-4-0613"` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `"gpt-4-32k"` - The safety checks reported by the API that have been acknowledged by the developer. + - `"gpt-4-32k-0314"` - - `id: string` + - `"gpt-4-32k-0613"` - The ID of the pending safety check. + - `"gpt-3.5-turbo"` - - `code: optional string` + - `"gpt-3.5-turbo-16k"` - The type of the pending safety check. + - `"gpt-3.5-turbo-0301"` - - `message: optional string` + - `"gpt-3.5-turbo-0613"` - Details about the pending safety check. + - `"gpt-3.5-turbo-1106"` - - `agent: optional object { agent_name }` + - `"gpt-3.5-turbo-0125"` - The agent that produced this item. + - `"gpt-3.5-turbo-16k-0613"` - - `agent_name: string` + - `"o1-pro"` - The canonical name of the agent that produced this item. + - `"o1-pro-2025-03-19"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"o3-pro"` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `"o3-pro-2025-06-10"` - - `"in_progress"` + - `"o3-deep-research"` - - `"completed"` + - `"o3-deep-research-2025-06-26"` - - `"incomplete"` + - `"o4-mini-deep-research"` - - `WebSearchCall object { id, action, status, 2 more }` + - `"o4-mini-deep-research-2025-06-26"` - The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + - `"computer-use-preview"` - - `id: string` + - `"computer-use-preview-2025-03-11"` - The unique ID of the web search tool call. + - `"gpt-5-codex"` - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `"gpt-5-pro"` - 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). + - `"gpt-5-pro-2025-10-06"` - - `Search object { type, queries, query, sources }` + - `"gpt-5.1-codex-max"` - Action type "search" - Performs a web search query. + - `string` - - `type: "search"` + - `object: "response"` - The action type. + The object type of this resource - always set to `response`. - - `"search"` + - `"response"` - - `queries: optional array of string` + - `output: array of BetaResponseOutputItem` - The search queries. + An array of content items generated by the model. - - `query: optional string` + - 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. - The search query. + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - - `sources: optional array of object { type, url }` + An output message from the model. - The sources used in the search. + - `FileSearchCall object { id, queries, status, 3 more }` - - `type: "url"` + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - The type of source. Always `url`. + - `id: string` - - `"url"` + The unique ID of the file search tool call. - - `url: string` + - `queries: array of string` - The URL of the source. + The queries used to search for files. - - `OpenPage object { type, url }` + - `status: "in_progress" or "searching" or "completed" or 2 more` - Action type "open_page" - Opens a specific URL from search results. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `type: "open_page"` + - `"in_progress"` - The action type. + - `"searching"` - - `"open_page"` + - `"completed"` - - `url: optional string` + - `"incomplete"` - The URL opened by the model. + - `"failed"` - - `FindInPage object { pattern, type, url }` + - `type: "file_search_call"` - Action type "find_in_page": Searches for a pattern within a loaded page. + The type of the file search tool call. Always `file_search_call`. - - `pattern: string` + - `"file_search_call"` - The pattern or text to search for within the page. + - `agent: optional object { agent_name }` - - `type: "find_in_page"` + The agent that produced this item. - The action type. + - `agent_name: string` - - `"find_in_page"` + The canonical name of the agent that produced this item. - - `url: string` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - The URL of the page searched for the pattern. + The results of the file search tool call. - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `attributes: optional map[string or number or boolean]` - The status of the web search tool call. + 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. - - `"in_progress"` + - `string` - - `"searching"` + - `number` - - `"completed"` + - `boolean` - - `"failed"` + - `file_id: optional string` - - `type: "web_search_call"` + The unique ID of the file. - The type of the web search tool call. Always `web_search_call`. + - `filename: optional string` - - `"web_search_call"` + The name of the file. - - `agent: optional object { agent_name }` + - `score: optional number` - The agent that produced this item. + The relevance score of the file - a value between 0 and 1. - - `agent_name: string` + - `text: optional string` - The canonical name of the agent that produced this item. + The text that was retrieved from the file. - `FunctionCall object { arguments, call_id, name, 6 more }` @@ -172599,207 +172266,205 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `FunctionCallOutput object { call_id, output, type, 4 more }` + - `FunctionCallOutput object { id, call_id, output, 5 more }` - The output of a function tool call. + - `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 BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - Text, image, or file output of the function tool call. + The output from the function call generated by your code. + Can be a string or an list of output content. - - `string` + - `StringOutput = string` - A JSON string of the output of the function tool call. + A string of the output of the function call. - - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - An array of content outputs (text, image, file) for the function tool call. + Text, image, or file output of the function call. - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` A text input to the model. - - `text: string` - - The text input to the model. - - - `type: "input_text"` - - The type of the input item. Always `input_text`. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `"input_text"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `prompt_cache_breakpoint: optional object { mode }` + - `BetaResponseInputFile object { type, detail, file_data, 4 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. + A file input to the model. - - `mode: "explicit"` + - `status: "in_progress" or "completed" or "incomplete"` - The breakpoint mode. Always `explicit`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"explicit"` + - `"in_progress"` - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + - `"completed"` - An image input to the model. Learn about [image inputs](/docs/guides/vision) + - `"incomplete"` - - `type: "input_image"` + - `type: "function_call_output"` - The type of the input item. Always `input_image`. + The type of the function tool call output. Always `function_call_output`. - - `"input_image"` + - `"function_call_output"` - - `detail: optional "low" or "high" or "auto" or "original"` + - `agent: optional object { agent_name }` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + The agent that produced this item. - - `"low"` + - `agent_name: string` - - `"high"` + The canonical name of the agent that produced this item. - - `"auto"` + - `caller: optional object { type } or object { caller_id, type }` - - `"original"` + The execution context that produced this tool call. - - `file_id: optional string` + - `Direct object { type }` - The ID of the file to be sent to the model. + - `type: "direct"` - - `image_url: optional string` + The caller type. Always `direct`. - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + - `"direct"` - - `prompt_cache_breakpoint: optional object { mode }` + - `Program object { caller_id, 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. + - `caller_id: string` - - `mode: "explicit"` + The call ID of the program item that produced this tool call. - The breakpoint mode. Always `explicit`. + - `type: "program"` - - `"explicit"` + The caller type. Always `program`. - - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` + - `"program"` - A file input to the model. + - `created_by: optional string` - - `type: "input_file"` + The identifier of the actor that created the item. - The type of the input item. Always `input_file`. + - `AgentMessage object { id, author, content, 3 more }` - - `"input_file"` + - `id: string` - - `detail: optional "auto" or "low" or "high"` + The unique ID of the agent message. - 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`. + - `author: string` - - `"auto"` + The sending agent identity. - - `"low"` + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - - `"high"` + Encrypted content sent between agents. - - `file_data: optional string` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - The base64-encoded data of the file to be sent to the model. + A text input to the model. - - `file_id: optional string` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - The ID of the file to be sent to the model. + A text output from the model. - - `file_url: optional string` + - `Text object { text, type }` - The URL of the file to be sent to the model. + A text content. - - `filename: optional string` + - `text: string` - The name of the file to be sent to the model. + - `type: "text"` - - `prompt_cache_breakpoint: optional object { mode }` + - `"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. + - `SummaryText object { text, type }` - - `mode: "explicit"` + A summary text from the model. - The breakpoint mode. Always `explicit`. + - `text: string` - - `"explicit"` + A summary of the reasoning output from the model so far. - - `type: "function_call_output"` + - `type: "summary_text"` - The type of the function tool call output. Always `function_call_output`. + The type of the object. Always `summary_text`. - - `"function_call_output"` + - `"summary_text"` - - `id: optional string` + - `ReasoningText object { text, type }` - The unique ID of the function tool call output. Populated when this item is returned via API. + Reasoning text from the model. - - `agent: optional object { agent_name }` + - `text: string` - The agent that produced this item. + The reasoning text from the model. - - `agent_name: string` + - `type: "reasoning_text"` - The canonical name of the agent that produced this item. + The type of the reasoning text. Always `reasoning_text`. - - `caller: optional object { type } or object { caller_id, type }` + - `"reasoning_text"` - The execution context that produced this tool call. + - `BetaResponseOutputRefusal object { refusal, type }` - - `Direct object { type }` + A refusal from the model. - - `type: "direct"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - The caller type. Always `direct`. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"direct"` + - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` - - `Program object { caller_id, type }` + A screenshot of a computer. - - `caller_id: string` + - `detail: "low" or "high" or "auto" or "original"` - The call ID of the program item that produced this tool call. + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `type: "program"` + - `"low"` - The caller type. Always `program`. + - `"high"` - - `"program"` + - `"auto"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"original"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `file_id: string` - - `"in_progress"` + The identifier of an uploaded file that contains the screenshot. - - `"completed"` + - `image_url: string` - - `"incomplete"` + The URL of the screenshot image. - - `AgentMessage object { author, content, recipient, 3 more }` + - `type: "computer_screenshot"` - A message routed between agents. + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `author: string` + - `"computer_screenshot"` - The sending agent identity. + - `prompt_cache_breakpoint: optional object { mode }` - - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, 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. - Plaintext, image, or encrypted content sent between agents. + - `mode: "explicit"` - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + The breakpoint mode. Always `explicit`. - A text input to the model. + - `"explicit"` - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - An image input to the model. Learn about [image inputs](/docs/guides/vision) + A file input to the model. - `EncryptedContent object { encrypted_content, type }` @@ -172821,14 +172486,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "agent_message"` - The item type. Always `agent_message`. + The type of the item. Always `agent_message`. - `"agent_message"` - - `id: optional string` - - The unique ID of this agent message item. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -172837,11 +172498,15 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `MultiAgentCall object { action, arguments, call_id, 3 more }` + - `MultiAgentCall object { id, action, arguments, 3 more }` + + - `id: string` + + The unique ID of the multi-agent call item. - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - The multi-agent action that was executed. + The multi-agent action to execute. - `"spawn_agent"` @@ -172857,7 +172522,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `arguments: string` - The action arguments as a JSON string. + The JSON string of arguments generated for the action. - `call_id: string` @@ -172865,14 +172530,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "multi_agent_call"` - The item type. Always `multi_agent_call`. + The type of the multi-agent call. Always `multi_agent_call`. - `"multi_agent_call"` - - `id: optional string` - - The unique ID of this multi-agent call. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -172881,7 +172542,11 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `MultiAgentCallOutput object { action, call_id, output, 3 more }` + - `MultiAgentCallOutput object { id, action, call_id, 3 more }` + + - `id: string` + + The unique ID of the multi-agent call output item. - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` @@ -172903,105 +172568,133 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The unique ID of the multi-agent call. - - `output: array of object { text, type, annotations }` + - `output: array of BetaResponseOutputText` Text output returned by the multi-agent action. + - `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. + + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `text: string` - The text content. + The text output from the model. - `type: "output_text"` - The content type. Always `output_text`. + The type of the output text. Always `output_text`. - - `"output_text"` + - `type: "multi_agent_call_output"` - - `annotations: optional 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 }` + The type of the multi-agent result. Always `multi_agent_call_output`. - Citations associated with the text content. + - `"multi_agent_call_output"` - - `FileCitation object { file_id, filename, index, type }` + - `agent: optional object { agent_name }` - - `file_id: string` + The agent that produced this item. - The ID of the file. + - `agent_name: string` - - `filename: string` + The canonical name of the agent that produced this item. - The filename of the file cited. + - `WebSearchCall object { id, action, status, 2 more }` - - `index: number` + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - The index of the file in the list of files. + - `id: string` - - `type: "file_citation"` + The unique ID of the web search tool call. - The citation type. Always `file_citation`. + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `"file_citation"` + 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). - - `URLCitation object { end_index, start_index, title, 2 more }` + - `Search object { type, queries, query, sources }` - - `end_index: number` + Action type "search" - Performs a web search query. - The index of the last character of the citation in the message. + - `type: "search"` - - `start_index: number` + The action type. - The index of the first character of the citation in the message. + - `"search"` - - `title: string` + - `queries: optional array of string` - The title of the cited resource. + The search queries. - - `type: "url_citation"` + - `query: optional string` - The citation type. Always `url_citation`. + The search query. - - `"url_citation"` + - `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 cited resource. + The URL of the source. - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + - `OpenPage object { type, url }` - - `container_id: string` + Action type "open_page" - Opens a specific URL from search results. - The ID of the container. + - `type: "open_page"` - - `end_index: number` + The action type. - The index of the last character of the citation in the message. + - `"open_page"` - - `file_id: string` + - `url: optional string` - The ID of the container file. + The URL opened by the model. - - `filename: string` + - `FindInPage object { pattern, type, url }` - The filename of the container file cited. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `start_index: number` + - `pattern: string` - The index of the first character of the citation in the message. + The pattern or text to search for within the page. - - `type: "container_file_citation"` + - `type: "find_in_page"` - The citation type. Always `container_file_citation`. + The action type. - - `"container_file_citation"` + - `"find_in_page"` - - `type: "multi_agent_call_output"` + - `url: string` - The item type. Always `multi_agent_call_output`. + The URL of the page searched for the pattern. - - `"multi_agent_call_output"` + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `id: optional string` + The status of the web search tool call. - The unique ID of this multi-agent call output. + - `"in_progress"` + + - `"searching"` + + - `"completed"` + + - `"failed"` + + - `type: "web_search_call"` + + The type of the web search tool call. Always `web_search_call`. + + - `"web_search_call"` - `agent: optional object { agent_name }` @@ -173011,21 +172704,60 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `ToolSearchCall object { arguments, type, id, 4 more }` + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - - `arguments: unknown` + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - The arguments supplied to the tool search call. + - `id: string` - - `type: "tool_search_call"` + The unique ID of the computer call. - The item type. Always `tool_search_call`. + - `call_id: string` - - `"tool_search_call"` + An identifier used when responding to the tool call with output. - - `id: optional string` + - `pending_safety_checks: array of object { id, code, message }` - The unique ID of this tool search call. + 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 BetaComputerAction` + + A click action. + + - `actions: optional BetaComputerActionList` + + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - `agent: optional object { agent_name }` @@ -173035,11 +172767,221 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `call_id: optional string` + - `ComputerCallOutput object { id, call_id, output, 5 more }` + + - `id: string` + + The unique ID of the computer call tool output. + + - `call_id: string` + + The ID of the computer tool call that produced the output. + + - `output: BetaResponseComputerToolCallOutputScreenshot` + + A computer screenshot image used with the computer use tool. + + - `status: "completed" or "incomplete" or "failed" or "in_progress"` + + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. + + - `"completed"` + + - `"incomplete"` + + - `"failed"` + + - `"in_progress"` + + - `type: "computer_call_output"` + + The type of the computer tool call output. Always `computer_call_output`. + + - `"computer_call_output"` + + - `acknowledged_safety_checks: optional array of object { id, code, message }` + + The safety checks reported by the API that have been acknowledged by the + developer. + + - `id: string` + + The ID of the pending safety check. + + - `code: optional string` + + The type of the pending safety check. + + - `message: optional string` + + Details about the pending safety check. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `Reasoning object { id, summary, type, 4 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 object { text, type }` + + 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"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `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"` + + - `Program object { id, call_id, code, 3 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"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `ProgramOutput object { id, call_id, result, 3 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"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `ToolSearchCall object { id, arguments, call_id, 5 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: optional "server" or "client"` + - `execution: "server" or "client"` Whether tool search was executed by the server or by the client. @@ -173047,9 +172989,9 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"client"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `status: "in_progress" or "completed" or "incomplete"` - The status of the tool search call. + The status of the tool search call item that was recorded. - `"in_progress"` @@ -173057,11 +172999,55 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `ToolSearchOutput object { tools, type, id, 4 more }` + - `type: "tool_search_call"` + + The type of the item. Always `tool_search_call`. + + - `"tool_search_call"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `ToolSearchOutput object { id, call_id, execution, 5 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 the tool search output. + The loaded tool definitions returned by tool search. - `Function object { name, parameters, strict, 5 more }` @@ -173582,40 +173568,8 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `BetaContainerNetworkPolicyDisabled object { type }` - - `type: "disabled"` - - Disable outbound network access. Always `disabled`. - - - `"disabled"` - - `BetaContainerNetworkPolicyAllowlist 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 BetaContainerNetworkPolicyDomainSecret` - - 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`. @@ -173796,128 +173750,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `BetaContainerAuto 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 BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - Network access policy for the container. - - - `BetaContainerNetworkPolicyDisabled object { type }` - - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - - `skills: optional array of BetaSkillReference or BetaInlineSkill` - - An optional list of skills referenced by id or inline data. - - - `BetaSkillReference 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. - - - `BetaInlineSkill object { description, name, source, type }` - - - `description: string` - - The description of the skill. - - - `name: string` - - The name of the skill. - - - `source: BetaInlineSkillSource` - - 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"` - - `BetaLocalEnvironment object { type, skills }` - - `type: "local"` - - Use a local computer environment. - - - `"local"` - - - `skills: optional array of BetaLocalSkill` - - 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. - - `BetaContainerReference 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) @@ -174204,14 +174040,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "tool_search_output"` - The item type. Always `tool_search_output`. + The type of the item. Always `tool_search_output`. - `"tool_search_output"` - - `id: optional string` - - The unique ID of this tool search output. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -174220,39 +174052,39 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `call_id: optional string` - - The unique ID of the tool search call generated by the model. + - `created_by: optional string` - - `execution: optional "server" or "client"` + The identifier of the actor that created the item. - Whether tool search was executed by the server or by the client. + - `AdditionalTools object { id, role, tools, 2 more }` - - `"server"` + - `id: string` - - `"client"` + The unique ID of the additional tools item. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `role: "unknown" or "user" or "assistant" or 5 more` - The status of the tool search output. + The role that provided the additional tools. - - `"in_progress"` + - `"unknown"` - - `"completed"` + - `"user"` - - `"incomplete"` + - `"assistant"` - - `AdditionalTools object { role, tools, type, 2 more }` + - `"system"` - - `role: "developer"` + - `"critic"` - The role that provided the additional tools. Only `developer` is supported. + - `"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` - A list of additional tools made available at this item. + The additional tool definitions made available at this item. - `Function object { name, parameters, strict, 5 more }` @@ -175245,14 +175077,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "additional_tools"` - The item type. Always `additional_tools`. + The type of the item. Always `additional_tools`. - `"additional_tools"` - - `id: optional string` - - The unique ID of this additional tools item. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -175261,83 +175089,17 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `Reasoning object { id, summary, type, 4 more }` + - `Compaction object { id, encrypted_content, type, 2 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). + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - `id: string` - The unique identifier of the reasoning content. - - - `summary: array of object { text, type }` - - 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"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `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, agent }` - - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + The unique ID of the compaction item. - `encrypted_content: string` - The encrypted content of the compaction summary. + The encrypted content that was produced by compaction. - `type: "compaction"` @@ -175345,10 +175107,6 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"compaction"` - - `id: optional string` - - The ID of the compaction item. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -175357,6 +175115,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. + - `created_by: optional string` + + The identifier of the actor that created the item. + - `ImageGenerationCall object { id, result, status, 2 more }` An image generation request made by the model. @@ -175574,9 +175336,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `ShellCall object { action, call_id, type, 5 more }` + - `ShellCall object { id, action, call_id, 6 more }` - A tool representing a request to execute one or more shell commands. + 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 }` @@ -175584,30 +175350,60 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `commands: array of string` - Ordered shell commands for the execution environment to run. - - - `max_output_length: optional number` + - `max_output_length: number` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + Optional maximum number of characters to return from each command. - - `timeout_ms: optional number` + - `timeout_ms: number` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + Optional timeout in milliseconds for the commands. - `call_id: string` The unique ID of the shell tool call generated by the model. + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + + Represents the use of a local environment to perform shell actions. + + - `BetaResponseLocalEnvironment object { type }` + + Represents the use of a local environment to perform shell actions. + + - `type: "local"` + + The environment type. Always `local`. + + - `"local"` + + - `BetaResponseContainerReference 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. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -175624,8 +175420,6 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "direct"` - The caller type. Always `direct`. - - `"direct"` - `Program object { caller_id, type }` @@ -175636,43 +175430,35 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "program"` - The caller type. Always `program`. - - `"program"` - - `environment: optional BetaLocalEnvironment or BetaContainerReference` - - The environment to execute the shell commands in. - - - `BetaLocalEnvironment object { type, skills }` - - - `BetaContainerReference object { container_id, type }` - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `created_by: optional string` - - `"in_progress"` + The ID of the entity that created this tool call. - - `"completed"` + - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` - - `"incomplete"` + The output of a shell tool call that was emitted. - - `ShellCallOutput object { call_id, output, type, 5 more }` + - `id: string` - The streamed output items emitted by a shell tool call. + The unique ID of the shell call output. Populated when this item is returned via API. - `call_id: string` The unique ID of the shell tool call generated by the model. - - `output: array of BetaResponseFunctionShellCallOutputContent` + - `max_output_length: number` - Captured chunks of stdout and stderr output, along with their associated outcomes. + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + + - `output: array of object { outcome, stderr, stdout, created_by }` + + An array of shell call output contents - `outcome: object { type } or object { exit_code, type }` - The exit or timeout outcome associated with this shell call. + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - `Timeout object { type }` @@ -175690,7 +175476,7 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `exit_code: number` - The exit code returned by the shell process. + Exit code from the shell process. - `type: "exit"` @@ -175700,21 +175486,31 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `stderr: string` - Captured stderr output for the shell call. + The standard error output that was captured. - `stdout: string` - Captured stdout output for the shell call. + The standard output that was captured. - - `type: "shell_call_output"` + - `created_by: optional string` - The type of the item. Always `shell_call_output`. + The identifier of the actor that created the item. - - `"shell_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 shell 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"` - `agent: optional object { agent_name }` @@ -175732,8 +175528,6 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "direct"` - The caller type. Always `direct`. - - `"direct"` - `Program object { caller_id, type }` @@ -175744,27 +175538,19 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "program"` - The caller type. Always `program`. - - `"program"` - - `max_output_length: optional number` - - The maximum number of UTF-8 characters captured for this shell call's combined output. - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the shell call output. + - `created_by: optional string` - - `"in_progress"` + The identifier of the actor that created the item. - - `"completed"` + - `ApplyPatchCall object { id, call_id, operation, 5 more }` - - `"incomplete"` + A tool call that applies file diffs by creating, deleting, or updating files. - - `ApplyPatchCall object { call_id, operation, status, 4 more }` + - `id: string` - A tool call representing a request to create, delete, or update files using diff patches. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - `call_id: string` @@ -175772,55 +175558,55 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - The specific create, delete, or update instruction for the apply_patch tool call. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - `CreateFile object { diff, path, type }` - Instruction for creating a new file via the apply_patch tool. + Instruction describing how to create a file via the apply_patch tool. - `diff: string` - Unified diff content to apply when creating the file. + Diff to apply. - `path: string` - Path of the file to create relative to the workspace root. + Path of the file to create. - `type: "create_file"` - The operation type. Always `create_file`. + Create a new file with the provided diff. - `"create_file"` - `DeleteFile object { path, type }` - Instruction for deleting an existing file via the apply_patch tool. + Instruction describing how to delete a file via the apply_patch tool. - `path: string` - Path of the file to delete relative to the workspace root. + Path of the file to delete. - `type: "delete_file"` - The operation type. Always `delete_file`. + Delete the specified file. - `"delete_file"` - `UpdateFile object { diff, path, type }` - Instruction for updating an existing file via the apply_patch tool. + Instruction describing how to update a file via the apply_patch tool. - `diff: string` - Unified diff content to apply to the existing file. + Diff to apply. - `path: string` - Path of the file to update relative to the workspace root. + Path of the file to update. - `type: "update_file"` - The operation type. Always `update_file`. + Update an existing file with the provided diff. - `"update_file"` @@ -175838,10 +175624,6 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"apply_patch_call"` - - `id: optional string` - - The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -175858,8 +175640,6 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "direct"` - The caller type. Always `direct`. - - `"direct"` - `Program object { caller_id, type }` @@ -175870,13 +175650,19 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "program"` - The caller type. Always `program`. - - `"program"` - - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` + - `created_by: optional string` - The streamed output emitted by an apply patch tool call. + The ID of the entity that created this tool call. + + - `ApplyPatchCallOutput object { id, call_id, status, 5 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` @@ -175896,10 +175682,6 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"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. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -175916,8 +175698,6 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "direct"` - The caller type. Always `direct`. - - `"direct"` - `Program object { caller_id, type }` @@ -175928,13 +175708,76 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "program"` - The caller type. Always `program`. - - `"program"` + - `created_by: optional string` + + The ID of the entity that created this tool call output. + - `output: optional string` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + Optional textual output returned by the apply patch tool. + + - `McpCall object { id, arguments, name, 7 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"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `approval_request_id: optional string` + + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + + - `error: optional string` + + The error from the tool call, if any. + + - `output: optional string` + + The output from the tool call. + + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"calling"` + + - `"failed"` - `McpListTools object { id, server_label, tools, 3 more }` @@ -176020,10 +175863,14 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` + - `McpApprovalResponse object { id, approval_request_id, approve, 3 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. @@ -176038,10 +175885,6 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"mcp_approval_response"` - - `id: optional string` - - The unique ID of the approval response - - `agent: optional object { agent_name }` The agent that produced this item. @@ -176054,31 +175897,31 @@ curl -X POST https://api.openai.com/v1/responses/compact \ Optional reason for the decision. - - `McpCall object { id, arguments, name, 7 more }` + - `CustomToolCall object { call_id, input, name, 5 more }` - An invocation of a tool on an MCP server. + A call to a custom tool created by the model. - - `id: string` + - `call_id: string` - The unique ID of the tool call. + An identifier used to map this custom tool call to a tool call output. - - `arguments: string` + - `input: string` - A JSON string of the arguments passed to the tool. + The input for the custom tool call generated by the model. - `name: string` - The name of the tool that was run. + The name of the custom tool being called. - - `server_label: string` + - `type: "custom_tool_call"` - The label of the MCP server running the tool. + The type of the custom tool call. Always `custom_tool_call`. - - `type: "mcp_call"` + - `"custom_tool_call"` - The type of the item. Always `mcp_call`. + - `id: optional string` - - `"mcp_call"` + The unique ID of the custom tool call in the OpenAI platform. - `agent: optional object { agent_name }` @@ -176088,36 +175931,35 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `approval_request_id: optional string` + - `caller: optional object { type } or object { caller_id, type }` - 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 execution context that produced this tool call. - - `error: optional string` + - `Direct object { type }` - The error from the tool call, if any. + - `type: "direct"` - - `output: optional string` + - `"direct"` - The output from the tool call. + - `Program object { caller_id, type }` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `caller_id: string` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + The call ID of the program item that produced this tool call. - - `"in_progress"` + - `type: "program"` - - `"completed"` + - `"program"` - - `"incomplete"` + - `namespace: optional string` - - `"calling"` + The namespace of the custom tool being called. - - `"failed"` + - `CustomToolCallOutput object { id, call_id, output, 5 more }` - - `CustomToolCallOutput object { call_id, output, type, 3 more }` + - `id: string` - The output of a custom tool call from your code, being sent back to the model. + The unique ID of the custom tool call output item. - `call_id: string` @@ -176148,16 +175990,23 @@ curl -X POST https://api.openai.com/v1/responses/compact \ 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. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -176176,4847 +176025,5290 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The caller type. Always `direct`. - - `"direct"` + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `parallel_tool_calls: boolean` + + Whether to allow the model to run tool calls in parallel. + + - `temperature: number` + + 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. + + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes 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 + the model can call. + + - `BetaToolChoiceOptions = "none" or "auto" or "required"` + + Controls which (if any) tool is called by the model. + + `none` means the model will not call any tool and instead generates a message. + + `auto` means the model can pick between generating a message or calling one or + more tools. + + `required` means the model must call one or more tools. + + - `"none"` + + - `"auto"` + + - `"required"` + + - `BetaToolChoiceAllowed object { mode, tools, type }` + + Constrains the tools available to the model to a pre-defined set. + + - `mode: "auto" or "required"` + + Constrains the tools available to the model to a pre-defined set. + + `auto` allows the model to pick from among the allowed tools and generate a + message. + + `required` requires the model to call one or more of the allowed tools. + + - `"auto"` + + - `"required"` + + - `tools: array of map[unknown]` + + A list of tool definitions that the model should be allowed to call. + + For the Responses API, the list of tool definitions might look like: + + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` + + - `type: "allowed_tools"` + + Allowed tool configuration type. Always `allowed_tools`. + + - `"allowed_tools"` + + - `BetaToolChoiceTypes object { type }` + + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](/docs/guides/tools). + + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + + The type of hosted tool the model should to use. Learn more about + [built-in tools](/docs/guides/tools). + + Allowed values are: + + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` + + - `"file_search"` + + - `"web_search_preview"` + + - `"computer"` + + - `"computer_use_preview"` + + - `"computer_use"` + + - `"web_search_preview_2025_03_11"` + + - `"image_generation"` + + - `"code_interpreter"` + + - `BetaToolChoiceFunction object { name, type }` + + Use this option to force the model to call a specific function. + + - `name: string` + + The name of the function to call. + + - `type: "function"` + + For function calling, the type is always `function`. + + - `"function"` + + - `BetaToolChoiceMcp object { server_label, type, name }` + + Use this option to force the model to call a specific tool on a remote MCP server. + + - `server_label: string` + + The label of the MCP server to use. + + - `type: "mcp"` + + For MCP tools, the type is always `mcp`. + + - `"mcp"` + + - `name: optional string` + + The name of the tool to call on the server. + + - `BetaToolChoiceCustom object { name, type }` + + Use this option to force the model to call a specific custom tool. + + - `name: string` + + The name of the custom tool to call. + + - `type: "custom"` + + For custom tool calling, the type is always `custom`. + + - `"custom"` + + - `BetaSpecificProgrammaticToolCallingParam object { type }` + + - `type: "programmatic_tool_calling"` + + The tool to call. Always `programmatic_tool_calling`. + + - `"programmatic_tool_calling"` + + - `BetaToolChoiceApplyPatch object { type }` + + Forces the model to call the apply_patch tool when executing a tool call. + + - `type: "apply_patch"` + + The tool to call. Always `apply_patch`. + + - `"apply_patch"` + + - `BetaToolChoiceShell object { type }` + + Forces the model to call the shell tool when a tool call is required. + + - `type: "shell"` + + The tool to call. Always `shell`. + + - `"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` + + 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. + + We support the following categories of tools: + + - **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. + + - `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 object { key, type, value } or object { filters, type }` + + 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 object { key, type, value } 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. + + - `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` + + - `unknown` + + - `type: "and" or "or"` + + Type of operation: `and` or `or`. + + - `"and"` + + - `"or"` + + - `max_num_results: optional number` + + The maximum number of results to return. This number should be between 1 and 50 inclusive. + + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + + Ranking options for search. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` + + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + + - `Computer object { type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `type: "web_search" or "web_search_2025_08_26"` + + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "low" or "medium" or "high"` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + + - `"low"` + + - `"medium"` + + - `"high"` + + - `user_location: optional object { city, country, region, 2 more }` + + The approximate location of the user. + + - `city: optional string` + + Free text input for the city of the user, e.g. `San Francisco`. + + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` - - `Program object { caller_id, type }` + The type of location approximation. Always `approximate`. - - `caller_id: string` + - `"approximate"` - The call ID of the program item that produced this tool call. + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `type: "program"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - The caller type. Always `program`. + - `server_label: string` - - `"program"` + A label for this MCP server, used to identify it in tool calls. - - `CustomToolCall object { call_id, input, name, 5 more }` + - `type: "mcp"` - A call to a custom tool created by the model. + The type of the MCP tool. Always `mcp`. - - `call_id: string` + - `"mcp"` - An identifier used to map this custom tool call to a tool call output. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `input: string` + The tool invocation context(s). - The input for the custom tool call generated by the model. + - `"direct"` - - `name: string` + - `"programmatic"` - The name of the custom tool being called. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `type: "custom_tool_call"` + List of allowed tool names or a filter object. - The type of the custom tool call. Always `custom_tool_call`. + - `McpAllowedTools = array of string` - - `"custom_tool_call"` + A string array of allowed tool names - - `id: optional string` + - `McpToolFilter object { read_only, tool_names }` - The unique ID of the custom tool call in the OpenAI platform. + A filter object to specify which tools are allowed. - - `agent: optional object { agent_name }` + - `read_only: optional boolean` - The agent that produced this item. + 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. - - `agent_name: string` + - `tool_names: optional array of string` - The canonical name of the agent that produced this item. + List of allowed tool names. - - `caller: optional object { type } or object { caller_id, type }` + - `authorization: optional string` - The execution context that produced this tool call. + 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. - - `Direct object { type }` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `type: "direct"` + 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"` + Currently supported `connector_id` values are: - - `Program object { caller_id, type }` + - 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` - - `caller_id: string` + - `"connector_dropbox"` - The call ID of the program item that produced this tool call. + - `"connector_gmail"` - - `type: "program"` + - `"connector_googlecalendar"` - - `"program"` + - `"connector_googledrive"` - - `namespace: optional string` + - `"connector_microsoftteams"` - The namespace of the custom tool being called. + - `"connector_outlookcalendar"` - - `CompactionTrigger object { type, agent }` + - `"connector_outlookemail"` - Compacts the current context. Must be the final input item. + - `"connector_sharepoint"` - - `type: "compaction_trigger"` + - `defer_loading: optional boolean` - The type of the item. Always `compaction_trigger`. + Whether this MCP tool is deferred and discovered via tool search. - - `"compaction_trigger"` + - `headers: optional map[string]` - - `agent: optional object { agent_name }` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The agent that produced this item. + - `require_approval: optional object { always, never } or "always" or "never"` - - `agent_name: string` + Specify which of the MCP server's tools require approval. - The canonical name of the agent that produced this item. + - `McpToolApprovalFilter object { always, never }` - - `ItemReference object { id, agent, 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. - An internal identifier for an item to reference. + - `always: optional object { read_only, tool_names }` - - `id: string` + A filter object to specify which tools are allowed. - The ID of the item to reference. + - `read_only: optional boolean` - - `agent: optional object { agent_name }` + 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 agent that produced this item. + - `tool_names: optional array of string` - - `agent_name: string` + List of allowed tool names. - The canonical name of the agent that produced this item. + - `never: optional object { read_only, tool_names }` - - `type: optional "item_reference"` + A filter object to specify which tools are allowed. - The type of item to reference. Always `item_reference`. + - `read_only: optional boolean` - - `"item_reference"` + 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. - - `Program object { id, call_id, code, 3 more }` + - `tool_names: optional array of string` - - `id: string` + List of allowed tool names. - The unique ID of this program item. + - `McpToolApprovalSetting = "always" or "never"` - - `call_id: 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. - The stable call ID of the program item. + - `"always"` - - `code: string` + - `"never"` - The JavaScript source executed by programmatic tool calling. + - `server_description: optional string` - - `fingerprint: string` + Optional description of the MCP server, used to provide more context. - Opaque program replay fingerprint that must be round-tripped. + - `server_url: optional string` - - `type: "program"` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - The item type. Always `program`. + - `tunnel_id: optional string` - - `"program"` + 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. - - `agent: optional object { agent_name }` + - `CodeInterpreter object { container, type, allowed_callers }` - The agent that produced this item. + A tool that runs Python code to help generate a response to a prompt. - - `agent_name: string` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - The canonical name of the agent that produced this item. + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - - `ProgramOutput object { id, call_id, result, 3 more }` + - `string` - - `id: string` + The container ID. - The unique ID of this program output item. + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `call_id: string` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The call ID of the program item. + - `type: "auto"` - - `result: string` + Always `auto`. - The result produced by the program item. + - `"auto"` - - `status: "completed" or "incomplete"` + - `file_ids: optional array of string` - The terminal status of the program output. + An optional list of uploaded files to make available to your code. - - `"completed"` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `"incomplete"` + The memory limit for the code interpreter container. - - `type: "program_output"` + - `"1g"` - The item type. Always `program_output`. + - `"4g"` - - `"program_output"` + - `"16g"` - - `agent: optional object { agent_name }` + - `"64g"` - The agent that produced this item. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `agent_name: string` + Network access policy for the container. - The canonical name of the agent that produced this item. + - `BetaContainerNetworkPolicyDisabled object { type }` - - `instructions: optional string` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - A system (or developer) message inserted into the model's context. + - `type: "code_interpreter"` - 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. + The type of the code interpreter tool. Always `code_interpreter`. - - `max_output_tokens: optional number` + - `"code_interpreter"` - 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). + - `allowed_callers: optional array of "direct" or "programmatic"` - - `max_tool_calls: optional number` + The tool invocation context(s). - 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. + - `"direct"` - - `metadata: optional map[string]` + - `"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. + - `ProgrammaticToolCalling object { type }` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `type: "programmatic_tool_calling"` - - `model: optional "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + The type of the tool. Always `programmatic_tool_calling`. - 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. + - `"programmatic_tool_calling"` - - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` + - `ImageGeneration object { type, action, background, 9 more }` - 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. + A tool that generates images using the GPT image models. - - `"gpt-5.6-sol"` + - `type: "image_generation"` - - `"gpt-5.6-terra"` + The type of the image generation tool. Always `image_generation`. - - `"gpt-5.6-luna"` + - `"image_generation"` - - `"gpt-5.4"` + - `action: optional "generate" or "edit" or "auto"` - - `"gpt-5.4-mini"` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `"gpt-5.4-nano"` + - `"generate"` - - `"gpt-5.4-mini-2026-03-17"` + - `"edit"` - - `"gpt-5.4-nano-2026-03-17"` + - `"auto"` - - `"gpt-5.3-chat-latest"` + - `background: optional "transparent" or "opaque" or "auto"` - - `"gpt-5.2"` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `"gpt-5.2-2025-12-11"` + - `"transparent"` - - `"gpt-5.2-chat-latest"` + - `"opaque"` - - `"gpt-5.2-pro"` + - `"auto"` - - `"gpt-5.2-pro-2025-12-11"` + - `input_fidelity: optional "high" or "low"` - - `"gpt-5.1"` + 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`. - - `"gpt-5.1-2025-11-13"` + - `"high"` - - `"gpt-5.1-codex"` + - `"low"` - - `"gpt-5.1-mini"` + - `input_image_mask: optional object { file_id, image_url }` - - `"gpt-5.1-chat-latest"` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `"gpt-5"` + - `file_id: optional string` - - `"gpt-5-mini"` + File ID for the mask image. - - `"gpt-5-nano"` + - `image_url: optional string` - - `"gpt-5-2025-08-07"` + Base64-encoded mask image. - - `"gpt-5-mini-2025-08-07"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `"gpt-5-nano-2025-08-07"` + The image generation model to use. Default: `gpt-image-1`. - - `"gpt-5-chat-latest"` + - `string` - - `"gpt-4.1"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `"gpt-4.1-mini"` + The image generation model to use. Default: `gpt-image-1`. - - `"gpt-4.1-nano"` + - `"gpt-image-1"` - - `"gpt-4.1-2025-04-14"` + - `"gpt-image-1-mini"` - - `"gpt-4.1-mini-2025-04-14"` + - `"gpt-image-1.5"` - - `"gpt-4.1-nano-2025-04-14"` + - `moderation: optional "auto" or "low"` - - `"o4-mini"` + Moderation level for the generated image. Default: `auto`. - - `"o4-mini-2025-04-16"` + - `"auto"` - - `"o3"` + - `"low"` - - `"o3-2025-04-16"` + - `output_compression: optional number` - - `"o3-mini"` + Compression level for the output image. Default: 100. - - `"o3-mini-2025-01-31"` + - `output_format: optional "png" or "webp" or "jpeg"` - - `"o1"` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `"o1-2024-12-17"` + - `"png"` - - `"o1-preview"` + - `"webp"` - - `"o1-preview-2024-09-12"` + - `"jpeg"` - - `"o1-mini"` + - `partial_images: optional number` - - `"o1-mini-2024-09-12"` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `"gpt-4o"` + - `quality: optional "low" or "medium" or "high" or "auto"` - - `"gpt-4o-2024-11-20"` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `"gpt-4o-2024-08-06"` + - `"low"` - - `"gpt-4o-2024-05-13"` + - `"medium"` - - `"gpt-4o-audio-preview"` + - `"high"` - - `"gpt-4o-audio-preview-2024-10-01"` + - `"auto"` - - `"gpt-4o-audio-preview-2024-12-17"` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `"gpt-4o-audio-preview-2025-06-03"` + 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`. - - `"gpt-4o-mini-audio-preview"` + - `string` - - `"gpt-4o-mini-audio-preview-2024-12-17"` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `"gpt-4o-search-preview"` + 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`. - - `"gpt-4o-mini-search-preview"` + - `"1024x1024"` - - `"gpt-4o-search-preview-2025-03-11"` + - `"1024x1536"` - - `"gpt-4o-mini-search-preview-2025-03-11"` + - `"1536x1024"` - - `"chatgpt-4o-latest"` + - `"auto"` - - `"codex-mini-latest"` + - `LocalShell object { type }` - - `"gpt-4o-mini"` + A tool that allows the model to execute shell commands in a local environment. - - `"gpt-4o-mini-2024-07-18"` + - `type: "local_shell"` - - `"gpt-4-turbo"` + The type of the local shell tool. Always `local_shell`. - - `"gpt-4-turbo-2024-04-09"` + - `"local_shell"` - - `"gpt-4-0125-preview"` + - `Shell object { type, allowed_callers, environment }` - - `"gpt-4-turbo-preview"` + A tool that allows the model to execute shell commands. - - `"gpt-4-1106-preview"` + - `type: "shell"` - - `"gpt-4-vision-preview"` + The type of the shell tool. Always `shell`. - - `"gpt-4"` + - `"shell"` - - `"gpt-4-0314"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"gpt-4-0613"` + The tool invocation context(s). - - `"gpt-4-32k"` + - `"direct"` - - `"gpt-4-32k-0314"` + - `"programmatic"` - - `"gpt-4-32k-0613"` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `"gpt-3.5-turbo"` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `"gpt-3.5-turbo-16k"` + - `BetaLocalEnvironment object { type, skills }` - - `"gpt-3.5-turbo-0301"` + - `BetaContainerReference object { container_id, type }` - - `"gpt-3.5-turbo-0613"` + - `Custom object { name, type, allowed_callers, 3 more }` - - `"gpt-3.5-turbo-1106"` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `"gpt-3.5-turbo-0125"` + - `name: string` - - `"gpt-3.5-turbo-16k-0613"` + The name of the custom tool, used to identify it in tool calls. - - `"o1-pro"` + - `type: "custom"` - - `"o1-pro-2025-03-19"` + The type of the custom tool. Always `custom`. - - `"o3-pro"` + - `"custom"` - - `"o3-pro-2025-06-10"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"o3-deep-research"` + The tool invocation context(s). - - `"o3-deep-research-2025-06-26"` + - `"direct"` - - `"o4-mini-deep-research"` + - `"programmatic"` - - `"o4-mini-deep-research-2025-06-26"` + - `defer_loading: optional boolean` - - `"computer-use-preview"` + Whether this tool should be deferred and discovered via tool search. - - `"computer-use-preview-2025-03-11"` + - `description: optional string` - - `"gpt-5-codex"` + Optional description of the custom tool, used to provide more context. - - `"gpt-5-pro"` + - `format: optional object { type } or object { definition, syntax, type }` - - `"gpt-5-pro-2025-10-06"` + The input format for the custom tool. Default is unconstrained text. - - `"gpt-5.1-codex-max"` + - `Text object { type }` - - `string` + Unconstrained free-form text. - - `moderation: optional object { model, policy }` + - `type: "text"` - Configuration for running moderation on the input and output of this response. + Unconstrained text format. Always `text`. - - `model: string` + - `"text"` - The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'. + - `Grammar object { definition, syntax, type }` - - `policy: optional object { input, output }` + A grammar defined by the user. - The policy to apply to moderated response input and output. + - `definition: string` - - `input: optional object { mode }` + The grammar definition. - The moderation policy for the response input. + - `syntax: "lark" or "regex"` - - `mode: "score" or "block"` + The syntax of the grammar definition. One of `lark` or `regex`. - - `"score"` + - `"lark"` - - `"block"` + - `"regex"` - - `output: optional object { mode }` + - `type: "grammar"` - The moderation policy for the response output. + Grammar format. Always `grammar`. - - `mode: "score" or "block"` + - `"grammar"` - - `"score"` + - `Namespace object { description, name, tools, type }` - - `"block"` + Groups function/custom tools under a shared namespace. - - `multi_agent: optional object { enabled, max_concurrent_subagents }` + - `description: string` - Configuration for server-hosted multi-agent execution. + A description of the namespace shown to the model. - - `enabled: boolean` + - `name: string` - Whether to enable server-hosted multi-agent execution for this response. + The namespace name used in tool calls (for example, `crm`). - - `max_concurrent_subagents: optional number` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - `max_concurrent_subagents` sets the maximum number of subagents that can be active simultaneously across the entire agent tree. It includes all descendants—children, grandchildren, and deeper subagents—but excludes the root agent. - The API does not impose a fixed upper bound on this setting. The default is `3`, which is recommended for most workloads. Multi-agent runs also have no fixed limit on tree depth or the total number of subagents created during a run. + The function/custom tools available inside this namespace. - - `parallel_tool_calls: optional boolean` + - `Function object { name, type, allowed_callers, 5 more }` - Whether to allow the model to run tool calls in parallel. + - `name: string` - - `previous_response_id: optional string` + - `type: "function"` - 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`. + - `"function"` - - `prompt: optional BetaResponsePrompt` + - `allowed_callers: optional array of "direct" or "programmatic"` - Reference to a prompt template and its variables. - [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). + The tool invocation context(s). - - `id: string` + - `"direct"` - The unique identifier of the prompt template to use. + - `"programmatic"` - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + - `defer_loading: optional boolean` - 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. + Whether this function should be deferred and discovered via tool search. - - `string` + - `description: optional string` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `output_schema: optional map[unknown]` - A text input to the model. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `parameters: optional unknown` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `strict: optional boolean` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + Whether to enforce strict parameter validation. If omitted, Responses attempts to use strict validation when the schema is compatible, and falls back to non-strict validation otherwise. - A file input to the model. + - `Custom object { name, type, allowed_callers, 3 more }` - - `version: optional string` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - Optional version of the prompt template. + - `name: string` - - `prompt_cache_key: optional string` + The name of the custom tool, used to identify it in tool calls. - 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). + - `type: "custom"` - - `prompt_cache_options: optional object { mode, ttl }` + The type of the custom tool. Always `custom`. - 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. + - `"custom"` - - `mode: optional "implicit" or "explicit"` + - `allowed_callers: optional array of "direct" or "programmatic"` - 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 tool invocation context(s). - - `"implicit"` + - `"direct"` - - `"explicit"` + - `"programmatic"` - - `ttl: optional "30m"` + - `defer_loading: optional boolean` - 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. + Whether this tool should be deferred and discovered via tool search. - - `"30m"` + - `description: optional string` - - `prompt_cache_retention: optional "in_memory" or "24h"` + Optional description of the custom tool, used to provide more context. - Deprecated. Use `prompt_cache_options.ttl` instead. + - `format: optional object { type } or object { definition, syntax, 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. + The input format for the custom tool. Default is unconstrained text. - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `Text object { type }` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + Unconstrained free-form text. - - `"in_memory"` + - `type: "text"` - - `"24h"` + Unconstrained text format. Always `text`. - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + - `"text"` - **gpt-5 and o-series models only** + - `Grammar object { definition, syntax, type }` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + A grammar defined by the user. - - `context: optional "auto" or "current_turn" or "all_turns"` + - `definition: 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`. + The grammar definition. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `syntax: "lark" or "regex"` - - `"auto"` + The syntax of the grammar definition. One of `lark` or `regex`. - - `"current_turn"` + - `"lark"` - - `"all_turns"` + - `"regex"` - - `effort: optional "none" or "minimal" or "low" or 4 more` + - `type: "grammar"` - 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. + Grammar format. Always `grammar`. - - `"none"` + - `"grammar"` - - `"minimal"` + - `type: "namespace"` - - `"low"` + The type of the tool. Always `namespace`. - - `"medium"` + - `"namespace"` - - `"high"` + - `ToolSearch object { type, description, execution, parameters }` - - `"xhigh"` + Hosted or BYOT tool search configuration for deferred tools. - - `"max"` + - `type: "tool_search"` - - `generate_summary: optional "auto" or "concise" or "detailed"` + The type of the tool. Always `tool_search`. - **Deprecated:** use `summary` instead. + - `"tool_search"` - 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`. + - `description: optional string` - - `"auto"` + Description shown to the model for a client-executed tool search tool. - - `"concise"` + - `execution: optional "server" or "client"` - - `"detailed"` + Whether tool search is executed by the server or by the client. - - `mode: optional string or "standard" or "pro"` + - `"server"` - Controls the reasoning execution mode for the request. + - `"client"` - When returned on a response, this is the effective execution mode. + - `parameters: optional unknown` - - `string` + Parameter schema for a client-executed tool search tool. - - `"standard" or "pro"` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - Controls the reasoning execution mode for the request. + 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). - When returned on a response, this is the effective execution mode. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `"standard"` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `"pro"` + - `"web_search_preview"` - - `summary: optional "auto" or "concise" or "detailed"` + - `"web_search_preview_2025_03_11"` - 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`. + - `search_content_types: optional array of "text" or "image"` - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `"text"` - - `"auto"` + - `"image"` - - `"concise"` + - `search_context_size: optional "low" or "medium" or "high"` - - `"detailed"` + 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. - - `safety_identifier: optional string` + - `"low"` - 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). + - `"medium"` - - `service_tier: optional "auto" or "default" or "flex" or 2 more` + - `"high"` - Specifies the processing type used for serving the request. + - `user_location: optional object { type, city, country, 2 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'. + The user's location. - 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: "approximate"` - - `"auto"` + The type of location approximation. Always `approximate`. - - `"default"` + - `"approximate"` - - `"flex"` + - `city: optional string` - - `"scale"` + Free text input for the city of the user, e.g. `San Francisco`. - - `"priority"` + - `country: optional string` - - `store: optional boolean` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - Whether to store the generated model response for later retrieval via - API. + - `region: optional string` - - `stream: optional boolean` + Free text input for the region of the user, e.g. `California`. - 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. + - `timezone: optional string` - - `stream_options: optional object { include_obfuscation }` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - Options for streaming responses. Only set this when you set `stream: true`. + - `ApplyPatch object { type, allowed_callers }` - - `include_obfuscation: optional boolean` + Allows the assistant to create, delete, or update files using unified diffs. - 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. + - `type: "apply_patch"` - - `temperature: optional number` + The type of the tool. Always `apply_patch`. - 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. + - `"apply_patch"` - - `text: optional BetaResponseTextConfig` + - `allowed_callers: optional array of "direct" or "programmatic"` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + The tool invocation context(s). - - [Text inputs and outputs](/docs/guides/text) - - [Structured Outputs](/docs/guides/structured-outputs) + - `"direct"` - - `format: optional BetaResponseFormatTextConfig` + - `"programmatic"` - An object specifying the format that the model must output. + - `top_p: number` - 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). + 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 default format is `{ "type": "text" }` with no additional options. + We generally recommend altering this or `temperature` but not both. - **Not recommended for gpt-4o and newer models:** + - `background: optional boolean` - 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. + Whether to run the model response in the background. + [Learn more](/docs/guides/background). - - `Text object { type }` + - `completed_at: optional number` - Default response format. Used to generate text responses. + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - - `type: "text"` + - `conversation: optional object { id }` - The type of response format being defined. Always `text`. + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - - `"text"` + - `id: string` - - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` + The unique ID of the conversation that this response was associated with. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + - `max_output_tokens: optional number` - - `name: 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 name of the response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + - `max_tool_calls: optional number` - - `schema: map[unknown]` + 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 schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `moderation: optional object { input, output }` - - `type: "json_schema"` + Moderation results for the response input and output, if moderated completions were requested. - The type of response format being defined. Always `json_schema`. + - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - - `"json_schema"` + Moderation for the response input. - - `description: optional string` + - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` - A description of what the response format is for, used by the model to - determine how to respond in the format. + A moderation result produced for the response input or output. - - `strict: optional boolean` + - `categories: map[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). + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `JSONObject object { type }` + - `category_applied_input_types: map[array of "text" or "image"]` - 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. + Which modalities of input are reflected by the score for each category. - - `type: "json_object"` + - `"text"` - The type of response format being defined. Always `json_object`. + - `"image"` - - `"json_object"` + - `category_scores: map[number]` - - `verbosity: optional "low" or "medium" or "high"` + A dictionary of moderation categories to scores. - 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`. + - `flagged: boolean` - - `"low"` + A boolean indicating whether the content was flagged by any category. - - `"medium"` + - `model: string` - - `"high"` + The moderation model that produced this result. - - `tool_choice: optional BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + - `type: "moderation_result"` - 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 object type, which was always `moderation_result` for successful moderation results. - - `BetaToolChoiceOptions = "none" or "auto" or "required"` + - `"moderation_result"` - Controls which (if any) tool is called by the model. + - `Error object { code, message, type }` - `none` means the model will not call any tool and instead generates a message. + An error produced while attempting moderation for the response input or output. - `auto` means the model can pick between generating a message or calling one or - more tools. + - `code: string` - `required` means the model must call one or more tools. + The error code. - - `"none"` + - `message: string` - - `"auto"` + The error message. - - `"required"` + - `type: "error"` - - `BetaToolChoiceAllowed object { mode, tools, type }` + The object type, which was always `error` for moderation failures. - Constrains the tools available to the model to a pre-defined set. + - `"error"` - - `mode: "auto" or "required"` + - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - Constrains the tools available to the model to a pre-defined set. + Moderation for the response output. - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` - `required` requires the model to call one or more of the allowed tools. + A moderation result produced for the response input or output. - - `"auto"` + - `categories: map[boolean]` - - `"required"` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `tools: array of map[unknown]` + - `category_applied_input_types: map[array of "text" or "image"]` - A list of tool definitions that the model should be allowed to call. + Which modalities of input are reflected by the score for each category. - For the Responses API, the list of tool definitions might look like: + - `"text"` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `"image"` - - `type: "allowed_tools"` + - `category_scores: map[number]` - Allowed tool configuration type. Always `allowed_tools`. + A dictionary of moderation categories to scores. - - `"allowed_tools"` + - `flagged: boolean` - - `BetaToolChoiceTypes object { type }` + A boolean indicating whether the content was flagged by any category. - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](/docs/guides/tools). + - `model: string` - - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + The moderation model that produced this result. - The type of hosted tool the model should to use. Learn more about - [built-in tools](/docs/guides/tools). + - `type: "moderation_result"` - Allowed values are: + The object type, which was always `moderation_result` for successful moderation results. - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `"moderation_result"` - - `"file_search"` + - `Error object { code, message, type }` - - `"web_search_preview"` + An error produced while attempting moderation for the response input or output. - - `"computer"` + - `code: string` - - `"computer_use_preview"` + The error code. - - `"computer_use"` + - `message: string` - - `"web_search_preview_2025_03_11"` + The error message. - - `"image_generation"` + - `type: "error"` - - `"code_interpreter"` + The object type, which was always `error` for moderation failures. - - `BetaToolChoiceFunction object { name, type }` + - `"error"` - Use this option to force the model to call a specific function. + - `output_text: optional string` - - `name: 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. - The name of the function to call. + - `previous_response_id: optional string` - - `type: "function"` + 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`. - For function calling, the type is always `function`. + - `prompt: optional BetaResponsePrompt` - - `"function"` + Reference to a prompt template and its variables. + [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). - - `BetaToolChoiceMcp object { server_label, type, name }` + - `id: string` - Use this option to force the model to call a specific tool on a remote MCP server. + The unique identifier of the prompt template to use. - - `server_label: string` + - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` - The label of the MCP server to use. + 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. - - `type: "mcp"` + - `string` - For MCP tools, the type is always `mcp`. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `"mcp"` + A text input to the model. - - `name: optional string` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - The name of the tool to call on the server. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `BetaToolChoiceCustom object { name, type }` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - Use this option to force the model to call a specific custom tool. + A file input to the model. - - `name: string` + - `version: optional string` - The name of the custom tool to call. + Optional version of the prompt template. - - `type: "custom"` + - `prompt_cache_key: optional string` - For custom tool calling, the type is always `custom`. + 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). - - `"custom"` + - `prompt_cache_options: optional object { mode, ttl }` - - `BetaSpecificProgrammaticToolCallingParam object { type }` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - - `type: "programmatic_tool_calling"` + - `mode: "implicit" or "explicit"` - The tool to call. Always `programmatic_tool_calling`. + Whether implicit prompt-cache breakpoints were enabled. - - `"programmatic_tool_calling"` + - `"implicit"` - - `BetaToolChoiceApplyPatch object { type }` + - `"explicit"` - Forces the model to call the apply_patch tool when executing a tool call. + - `ttl: "30m"` - - `type: "apply_patch"` + The minimum lifetime applied to each cache breakpoint. - The tool to call. Always `apply_patch`. + - `"30m"` - - `"apply_patch"` + - `prompt_cache_retention: optional "in_memory" or "24h"` - - `BetaToolChoiceShell object { type }` + Deprecated. Use `prompt_cache_options.ttl` instead. - Forces the model to call the shell tool when a tool call is required. + 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. - - `type: "shell"` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - The tool to call. Always `shell`. + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `"shell"` + - `"in_memory"` - - `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` + - `"24h"` - 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. + - `reasoning: optional object { context, effort, generate_summary, 2 more }` - We support the following categories of tools: + **gpt-5 and o-series models only** - - **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. + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `Function object { name, parameters, strict, 5 more }` + - `context: optional "auto" or "current_turn" or "all_turns"` - 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). + 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`. - - `name: string` + When returned on a response, this is the effective reasoning context mode + used for the response. - The name of the function to call. + - `"auto"` - - `parameters: map[unknown]` + - `"current_turn"` - A JSON schema object describing the parameters of the function. + - `"all_turns"` - - `strict: boolean` + - `effort: optional "none" or "minimal" or "low" or 4 more` - Whether strict parameter validation is enforced for this function tool. + 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. - - `type: "function"` + - `"none"` - The type of the function tool. Always `function`. + - `"minimal"` - - `"function"` + - `"low"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"medium"` - The tool invocation context(s). + - `"high"` - - `"direct"` + - `"xhigh"` - - `"programmatic"` + - `"max"` - - `defer_loading: optional boolean` + - `generate_summary: optional "auto" or "concise" or "detailed"` - Whether this function is deferred and loaded via tool search. + **Deprecated:** use `summary` instead. - - `description: optional 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`. - A description of the function. Used by the model to determine whether or not to call the function. + - `"auto"` - - `output_schema: optional map[unknown]` + - `"concise"` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `"detailed"` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `mode: optional string or "standard" or "pro"` - 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). + Controls the reasoning execution mode for the request. - - `type: "file_search"` + When returned on a response, this is the effective execution mode. - The type of the file search tool. Always `file_search`. + - `string` - - `"file_search"` + - `"standard" or "pro"` - - `vector_store_ids: array of string` + Controls the reasoning execution mode for the request. - The IDs of the vector stores to search. + When returned on a response, this is the effective execution mode. - - `filters: optional object { key, type, value } or object { filters, type }` + - `"standard"` - A filter to apply. + - `"pro"` - - `ComparisonFilter object { key, type, value }` + - `summary: optional "auto" or "concise" or "detailed"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + 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`. - - `key: string` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - The key to compare against the value. + - `"auto"` - - `type: "eq" or "ne" or "gt" or 5 more` + - `"concise"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"detailed"` - - `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 + - `safety_identifier: optional string` - - `"eq"` + 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). - - `"ne"` + - `service_tier: optional "auto" or "default" or "flex" or 2 more` - - `"gt"` + Specifies the processing type used for serving the request. - - `"gte"` + - 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'. - - `"lt"` + 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. - - `"lte"` + - `"auto"` - - `"in"` + - `"default"` - - `"nin"` + - `"flex"` - - `value: string or number or boolean or array of string or number` + - `"scale"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `"priority"` - - `string` + - `status: optional BetaResponseStatus` - - `number` + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `boolean` + - `"completed"` - - `array of string or number` + - `"failed"` - - `string` + - `"in_progress"` - - `number` + - `"cancelled"` - - `CompoundFilter object { filters, type }` + - `"queued"` - Combine multiple filters using `and` or `or`. + - `"incomplete"` - - `filters: array of object { key, type, value } or unknown` + - `text: optional BetaResponseTextConfig` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `ComparisonFilter object { key, type, value }` + - [Text inputs and outputs](/docs/guides/text) + - [Structured Outputs](/docs/guides/structured-outputs) - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `format: optional BetaResponseFormatTextConfig` - - `key: string` + An object specifying the format that the model must output. - The key to compare against the value. + 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). - - `type: "eq" or "ne" or "gt" or 5 more` + The default format is `{ "type": "text" }` with no additional options. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + **Not recommended for gpt-4o and newer models:** - - `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 + 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. - - `"eq"` + - `Text object { type }` - - `"ne"` + Default response format. Used to generate text responses. - - `"gt"` + - `type: "text"` - - `"gte"` + The type of response format being defined. Always `text`. - - `"lt"` + - `"text"` - - `"lte"` + - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` - - `"in"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `"nin"` + - `name: string` - - `value: string or number or boolean or array of string or number` + 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 value to compare against the attribute key; supports string, number, or boolean types. + - `schema: map[unknown]` - - `string` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `number` + - `type: "json_schema"` - - `boolean` + The type of response format being defined. Always `json_schema`. - - `array of string or number` + - `"json_schema"` - - `string` + - `description: optional string` - - `number` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `unknown` + - `strict: optional boolean` - - `type: "and" or "or"` + 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 of operation: `and` or `or`. + - `JSONObject object { type }` - - `"and"` + 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. - - `"or"` + - `type: "json_object"` - - `max_num_results: optional number` + The type of response format being defined. Always `json_object`. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `"json_object"` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `verbosity: optional "low" or "medium" or "high"` - Ranking options for search. + 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`. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `"low"` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `"medium"` - - `embedding_weight: number` + - `"high"` - The weight of the embedding in the reciprocal ranking fusion. + - `top_logprobs: optional number` - - `text_weight: 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. - The weight of the text in the reciprocal ranking fusion. + - `truncation: optional "auto" or "disabled"` - - `ranker: optional "auto" or "default-2024-11-15"` + The truncation strategy to use for the model response. - The ranker to use for the file search. + - `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"` - - `"default-2024-11-15"` + - `"disabled"` - - `score_threshold: optional number` + - `usage: optional BetaResponseUsage` - 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. + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - - `Computer object { type }` + - `input_tokens: number` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The number of input tokens. - - `type: "computer"` + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` - The type of the computer tool. Always `computer`. + A detailed breakdown of the input tokens. - - `"computer"` + - `cache_write_tokens: number` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + The number of input tokens that were written to the cache. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `cached_tokens: number` - - `display_height: number` + The number of tokens that were retrieved from the cache. + [More on prompt caching](/docs/guides/prompt-caching). - The height of the computer display. + - `output_tokens: number` - - `display_width: number` + The number of output tokens. - The width of the computer display. + - `output_tokens_details: object { reasoning_tokens }` - - `environment: "windows" or "mac" or "linux" or 2 more` + A detailed breakdown of the output tokens. - The type of computer environment to control. + - `reasoning_tokens: number` - - `"windows"` + The number of reasoning tokens. - - `"mac"` + - `total_tokens: number` - - `"linux"` + The total number of tokens used. - - `"ubuntu"` + - `user: optional string` - - `"browser"` + 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: "computer_use_preview"` + - `sequence_number: number` - The type of the computer use tool. Always `computer_use_preview`. + The sequence number for this event. - - `"computer_use_preview"` + - `type: "response.completed"` - - `WebSearch object { type, filters, search_context_size, user_location }` + The type of the event. Always `response.completed`. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + - `"response.completed"` - - `type: "web_search" or "web_search_2025_08_26"` + - `agent: optional object { agent_name }` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + The agent that owns this multi-agent streaming event. - - `"web_search"` + - `agent_name: string` - - `"web_search_2025_08_26"` + The canonical name of the agent that produced this item. - - `filters: optional object { allowed_domains }` + - `BetaResponseContentPartAddedEvent object { content_index, item_id, output_index, 4 more }` - Filters for the search. + Emitted when a new content part is added. - - `allowed_domains: optional array of string` + - `content_index: number` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + The index of the content part that was added. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `item_id: string` - - `search_context_size: optional "low" or "medium" or "high"` + The ID of the output item that the content part was added to. - 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. + - `output_index: number` - - `"low"` + The index of the output item that the content part was added to. - - `"medium"` + - `part: BetaResponseOutputText or BetaResponseOutputRefusal or object { text, type }` - - `"high"` + The content part that was added. - - `user_location: optional object { city, country, region, 2 more }` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - The approximate location of the user. + A text output from the model. - - `city: optional string` + - `BetaResponseOutputRefusal object { refusal, type }` - Free text input for the city of the user, e.g. `San Francisco`. + A refusal from the model. - - `country: optional string` + - `ReasoningText object { text, type }` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + Reasoning text from the model. - - `region: optional string` + - `text: string` - Free text input for the region of the user, e.g. `California`. + The reasoning text from the model. - - `timezone: optional string` + - `type: "reasoning_text"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The type of the reasoning text. Always `reasoning_text`. - - `type: optional "approximate"` + - `"reasoning_text"` - The type of location approximation. Always `approximate`. + - `sequence_number: number` - - `"approximate"` + The sequence number of this event. - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `type: "response.content_part.added"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + The type of the event. Always `response.content_part.added`. - - `server_label: string` + - `"response.content_part.added"` - A label for this MCP server, used to identify it in tool calls. + - `agent: optional object { agent_name }` - - `type: "mcp"` + The agent that owns this multi-agent streaming event. - The type of the MCP tool. Always `mcp`. + - `agent_name: string` - - `"mcp"` + The canonical name of the agent that produced this item. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `BetaResponseContentPartDoneEvent object { content_index, item_id, output_index, 4 more }` - The tool invocation context(s). + Emitted when a content part is done. - - `"direct"` + - `content_index: number` - - `"programmatic"` + The index of the content part that is done. - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `item_id: string` - List of allowed tool names or a filter object. + The ID of the output item that the content part was added to. - - `McpAllowedTools = array of string` + - `output_index: number` - A string array of allowed tool names + The index of the output item that the content part was added to. - - `McpToolFilter object { read_only, tool_names }` + - `part: BetaResponseOutputText or BetaResponseOutputRefusal or object { text, type }` - A filter object to specify which tools are allowed. + The content part that is done. - - `read_only: optional boolean` + - `BetaResponseOutputText object { annotations, logprobs, text, 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. + A text output from the model. - - `tool_names: optional array of string` + - `BetaResponseOutputRefusal object { refusal, type }` - List of allowed tool names. + A refusal from the model. - - `authorization: optional string` + - `ReasoningText object { text, type }` - 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. + Reasoning text from the model. - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `text: 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 reasoning text from the model. - Currently supported `connector_id` values are: + - `type: "reasoning_text"` - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + The type of the reasoning text. Always `reasoning_text`. - - `"connector_dropbox"` + - `"reasoning_text"` - - `"connector_gmail"` + - `sequence_number: number` - - `"connector_googlecalendar"` + The sequence number of this event. - - `"connector_googledrive"` + - `type: "response.content_part.done"` - - `"connector_microsoftteams"` + The type of the event. Always `response.content_part.done`. - - `"connector_outlookcalendar"` + - `"response.content_part.done"` - - `"connector_outlookemail"` + - `agent: optional object { agent_name }` - - `"connector_sharepoint"` + The agent that owns this multi-agent streaming event. - - `defer_loading: optional boolean` + - `agent_name: string` - Whether this MCP tool is deferred and discovered via tool search. + The canonical name of the agent that produced this item. - - `headers: optional map[string]` + - `BetaResponseCreatedEvent object { response, sequence_number, type, agent }` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + An event that is emitted when a response is created. - - `require_approval: optional object { always, never } or "always" or "never"` + - `response: BetaResponse` - Specify which of the MCP server's tools require approval. + The response that was created. - - `McpToolApprovalFilter object { always, never }` + - `sequence_number: number` - 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 sequence number for this event. - - `always: optional object { read_only, tool_names }` + - `type: "response.created"` - A filter object to specify which tools are allowed. + The type of the event. Always `response.created`. - - `read_only: optional boolean` + - `"response.created"` - 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. + - `agent: optional object { agent_name }` - - `tool_names: optional array of string` + The agent that owns this multi-agent streaming event. - List of allowed tool names. + - `agent_name: string` - - `never: optional object { read_only, tool_names }` + The canonical name of the agent that produced this item. - A filter object to specify which tools are allowed. + - `BetaResponseErrorEvent object { code, message, param, 3 more }` - - `read_only: optional boolean` + Emitted when an error occurs. - 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. + - `code: string` - - `tool_names: optional array of string` + The error code. - List of allowed tool names. + - `message: string` - - `McpToolApprovalSetting = "always" or "never"` + The error 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. + - `param: string` - - `"always"` + The error parameter. - - `"never"` + - `sequence_number: number` - - `server_description: optional string` + The sequence number of this event. - Optional description of the MCP server, used to provide more context. + - `type: "error"` - - `server_url: optional string` + The type of the event. Always `error`. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `"error"` - - `tunnel_id: optional string` + - `agent: optional object { agent_name }` - 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 agent that owns this multi-agent streaming event. - - `CodeInterpreter object { container, type, allowed_callers }` + - `agent_name: string` - A tool that runs Python code to help generate a response to a prompt. + The canonical name of the agent that produced this item. - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `BetaResponseFileSearchCallCompletedEvent object { item_id, output_index, sequence_number, 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. + Emitted when a file search call is completed (results found). - - `string` + - `item_id: string` - The container ID. + The ID of the output item that the file search call is initiated. - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `output_index: number` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + The index of the output item that the file search call is initiated. - - `type: "auto"` + - `sequence_number: number` - Always `auto`. + The sequence number of this event. - - `"auto"` + - `type: "response.file_search_call.completed"` - - `file_ids: optional array of string` + The type of the event. Always `response.file_search_call.completed`. - An optional list of uploaded files to make available to your code. + - `"response.file_search_call.completed"` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `agent: optional object { agent_name }` - The memory limit for the code interpreter container. + The agent that owns this multi-agent streaming event. - - `"1g"` + - `agent_name: string` - - `"4g"` + The canonical name of the agent that produced this item. - - `"16g"` + - `BetaResponseFileSearchCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` - - `"64g"` + Emitted when a file search call is initiated. - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `item_id: string` - Network access policy for the container. + The ID of the output item that the file search call is initiated. - - `BetaContainerNetworkPolicyDisabled object { type }` + - `output_index: number` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + The index of the output item that the file search call is initiated. - - `type: "code_interpreter"` + - `sequence_number: number` - The type of the code interpreter tool. Always `code_interpreter`. + The sequence number of this event. - - `"code_interpreter"` + - `type: "response.file_search_call.in_progress"` - - `allowed_callers: optional array of "direct" or "programmatic"` + The type of the event. Always `response.file_search_call.in_progress`. - The tool invocation context(s). + - `"response.file_search_call.in_progress"` - - `"direct"` + - `agent: optional object { agent_name }` - - `"programmatic"` + The agent that owns this multi-agent streaming event. - - `ProgrammaticToolCalling object { type }` + - `agent_name: string` - - `type: "programmatic_tool_calling"` + The canonical name of the agent that produced this item. - The type of the tool. Always `programmatic_tool_calling`. + - `BetaResponseFileSearchCallSearchingEvent object { item_id, output_index, sequence_number, 2 more }` - - `"programmatic_tool_calling"` + Emitted when a file search is currently searching. - - `ImageGeneration object { type, action, background, 9 more }` + - `item_id: string` - A tool that generates images using the GPT image models. + The ID of the output item that the file search call is initiated. - - `type: "image_generation"` + - `output_index: number` - The type of the image generation tool. Always `image_generation`. + The index of the output item that the file search call is searching. - - `"image_generation"` + - `sequence_number: number` - - `action: optional "generate" or "edit" or "auto"` + The sequence number of this event. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `type: "response.file_search_call.searching"` - - `"generate"` + The type of the event. Always `response.file_search_call.searching`. - - `"edit"` + - `"response.file_search_call.searching"` - - `"auto"` + - `agent: optional object { agent_name }` - - `background: optional "transparent" or "opaque" or "auto"` + The agent that owns this multi-agent streaming event. - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + - `agent_name: string` - - `"transparent"` + The canonical name of the agent that produced this item. - - `"opaque"` + - `BetaResponseFunctionCallArgumentsDeltaEvent object { delta, item_id, output_index, 3 more }` - - `"auto"` + Emitted when there is a partial function-call arguments delta. - - `input_fidelity: optional "high" or "low"` + - `delta: 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 function-call arguments delta that is added. - - `"high"` + - `item_id: string` - - `"low"` + The ID of the output item that the function-call arguments delta is added to. - - `input_image_mask: optional object { file_id, image_url }` + - `output_index: number` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + The index of the output item that the function-call arguments delta is added to. - - `file_id: optional string` + - `sequence_number: number` - File ID for the mask image. + The sequence number of this event. - - `image_url: optional string` + - `type: "response.function_call_arguments.delta"` - Base64-encoded mask image. + The type of the event. Always `response.function_call_arguments.delta`. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"response.function_call_arguments.delta"` - The image generation model to use. Default: `gpt-image-1`. + - `agent: optional object { agent_name }` - - `string` + The agent that owns this multi-agent streaming event. - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `agent_name: string` - The image generation model to use. Default: `gpt-image-1`. + The canonical name of the agent that produced this item. - - `"gpt-image-1"` + - `BetaResponseFunctionCallArgumentsDoneEvent object { arguments, item_id, name, 4 more }` - - `"gpt-image-1-mini"` + Emitted when function-call arguments are finalized. - - `"gpt-image-1.5"` + - `arguments: string` - - `moderation: optional "auto" or "low"` + The function-call arguments. - Moderation level for the generated image. Default: `auto`. + - `item_id: string` - - `"auto"` + The ID of the item. - - `"low"` + - `name: string` - - `output_compression: optional number` + The name of the function that was called. - Compression level for the output image. Default: 100. + - `output_index: number` - - `output_format: optional "png" or "webp" or "jpeg"` + The index of the output item. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `sequence_number: number` - - `"png"` + The sequence number of this event. - - `"webp"` + - `type: "response.function_call_arguments.done"` - - `"jpeg"` + - `"response.function_call_arguments.done"` - - `partial_images: optional number` + - `agent: optional object { agent_name }` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + The agent that owns this multi-agent streaming event. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `agent_name: string` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The canonical name of the agent that produced this item. - - `"low"` + - `BetaResponseInProgressEvent object { response, sequence_number, type, agent }` - - `"medium"` + Emitted when the response is in progress. - - `"high"` + - `response: BetaResponse` - - `"auto"` + The response that is in progress. - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `sequence_number: number` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + The sequence number of this event. - - `string` + - `type: "response.in_progress"` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The type of the event. Always `response.in_progress`. - 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`. + - `"response.in_progress"` - - `"1024x1024"` + - `agent: optional object { agent_name }` - - `"1024x1536"` + The agent that owns this multi-agent streaming event. - - `"1536x1024"` + - `agent_name: string` - - `"auto"` + The canonical name of the agent that produced this item. - - `LocalShell object { type }` + - `BetaResponseFailedEvent object { response, sequence_number, type, agent }` - A tool that allows the model to execute shell commands in a local environment. + An event that is emitted when a response fails. - - `type: "local_shell"` + - `response: BetaResponse` - The type of the local shell tool. Always `local_shell`. + The response that failed. - - `"local_shell"` + - `sequence_number: number` - - `Shell object { type, allowed_callers, environment }` + The sequence number of this event. - A tool that allows the model to execute shell commands. + - `type: "response.failed"` - - `type: "shell"` + The type of the event. Always `response.failed`. - The type of the shell tool. Always `shell`. + - `"response.failed"` - - `"shell"` + - `agent: optional object { agent_name }` - - `allowed_callers: optional array of "direct" or "programmatic"` + The agent that owns this multi-agent streaming event. - The tool invocation context(s). + - `agent_name: string` - - `"direct"` + The canonical name of the agent that produced this item. - - `"programmatic"` + - `BetaResponseIncompleteEvent object { response, sequence_number, type, agent }` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + An event that is emitted when a response finishes as incomplete. - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `response: BetaResponse` - - `BetaLocalEnvironment object { type, skills }` + The response that was incomplete. - - `BetaContainerReference object { container_id, type }` + - `sequence_number: number` - - `Custom object { name, type, allowed_callers, 3 more }` + The sequence number of this event. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `type: "response.incomplete"` - - `name: string` + The type of the event. Always `response.incomplete`. - The name of the custom tool, used to identify it in tool calls. + - `"response.incomplete"` - - `type: "custom"` + - `agent: optional object { agent_name }` - The type of the custom tool. Always `custom`. + The agent that owns this multi-agent streaming event. - - `"custom"` + - `agent_name: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The canonical name of the agent that produced this item. - The tool invocation context(s). + - `BetaResponseOutputItemAddedEvent object { item, output_index, sequence_number, 2 more }` - - `"direct"` + Emitted when a new output item is added. - - `"programmatic"` + - `item: BetaResponseOutputItem` - - `defer_loading: optional boolean` + The output item that was added. - Whether this tool should be deferred and discovered via tool search. + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - - `description: optional string` + An output message from the model. - Optional description of the custom tool, used to provide more context. + - `FileSearchCall object { id, queries, status, 3 more }` - - `format: optional object { type } or object { definition, syntax, type }` + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - The input format for the custom tool. Default is unconstrained text. + - `FunctionCall object { arguments, call_id, name, 6 more }` - - `Text object { type }` + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - Unconstrained free-form text. + - `FunctionCallOutput object { id, call_id, output, 5 more }` - - `type: "text"` + - `AgentMessage object { id, author, content, 3 more }` - Unconstrained text format. Always `text`. + - `MultiAgentCall object { id, action, arguments, 3 more }` - - `"text"` + - `MultiAgentCallOutput object { id, action, call_id, 3 more }` - - `Grammar object { definition, syntax, type }` + - `WebSearchCall object { id, action, status, 2 more }` - A grammar defined by the user. + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `definition: string` + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - The grammar definition. + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - - `syntax: "lark" or "regex"` + - `ComputerCallOutput object { id, call_id, output, 5 more }` - The syntax of the grammar definition. One of `lark` or `regex`. + - `Reasoning object { id, summary, type, 4 more }` - - `"lark"` + 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). - - `"regex"` + - `Program object { id, call_id, code, 3 more }` - - `type: "grammar"` + - `ProgramOutput object { id, call_id, result, 3 more }` - Grammar format. Always `grammar`. + - `ToolSearchCall object { id, arguments, call_id, 5 more }` - - `"grammar"` + - `ToolSearchOutput object { id, call_id, execution, 5 more }` - - `Namespace object { description, name, tools, type }` + - `AdditionalTools object { id, role, tools, 2 more }` - Groups function/custom tools under a shared namespace. + - `Compaction object { id, encrypted_content, type, 2 more }` - - `description: string` + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - A description of the namespace shown to the model. + - `ImageGenerationCall object { id, result, status, 2 more }` - - `name: string` + An image generation request made by the model. - The namespace name used in tool calls (for example, `crm`). + - `CodeInterpreterCall object { id, code, container_id, 4 more }` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + A tool call to run code. - The function/custom tools available inside this namespace. + - `LocalShellCall object { id, action, call_id, 3 more }` - - `Function object { name, type, allowed_callers, 5 more }` + A tool call to run a command on the local shell. - - `name: string` + - `LocalShellCallOutput object { id, output, type, 2 more }` - - `type: "function"` + The output of a local shell tool call. - - `"function"` + - `ShellCall object { id, action, call_id, 6 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + A tool call that executes one or more shell commands in a managed environment. - The tool invocation context(s). + - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` - - `"direct"` + The output of a shell tool call that was emitted. - - `"programmatic"` + - `ApplyPatchCall object { id, call_id, operation, 5 more }` - - `defer_loading: optional boolean` + A tool call that applies file diffs by creating, deleting, or updating files. - Whether this function should be deferred and discovered via tool search. + - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` - - `description: optional string` + The output emitted by an apply patch tool call. - - `output_schema: optional map[unknown]` + - `McpCall object { id, arguments, name, 7 more }` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + An invocation of a tool on an MCP server. - - `parameters: optional unknown` + - `McpListTools object { id, server_label, tools, 3 more }` - - `strict: optional boolean` + A list of tools available on an MCP server. - 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. + - `McpApprovalRequest object { id, arguments, name, 3 more }` - - `Custom object { name, type, allowed_callers, 3 more }` + A request for human approval of a tool invocation. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` - - `name: string` + A response to an MCP approval request. - The name of the custom tool, used to identify it in tool calls. + - `CustomToolCall object { call_id, input, name, 5 more }` - - `type: "custom"` + A call to a custom tool created by the model. - The type of the custom tool. Always `custom`. + - `CustomToolCallOutput object { id, call_id, output, 5 more }` - - `"custom"` + - `output_index: number` - - `allowed_callers: optional array of "direct" or "programmatic"` + The index of the output item that was added. - The tool invocation context(s). + - `sequence_number: number` - - `"direct"` + The sequence number of this event. - - `"programmatic"` + - `type: "response.output_item.added"` - - `defer_loading: optional boolean` + The type of the event. Always `response.output_item.added`. - Whether this tool should be deferred and discovered via tool search. + - `"response.output_item.added"` - - `description: optional string` + - `agent: optional object { agent_name }` - Optional description of the custom tool, used to provide more context. + The agent that owns this multi-agent streaming event. - - `format: optional object { type } or object { definition, syntax, type }` + - `agent_name: string` - The input format for the custom tool. Default is unconstrained text. + The canonical name of the agent that produced this item. - - `Text object { type }` + - `BetaResponseOutputItemDoneEvent object { item, output_index, sequence_number, 2 more }` - Unconstrained free-form text. + Emitted when an output item is marked done. - - `type: "text"` + - `item: BetaResponseOutputItem` - Unconstrained text format. Always `text`. + The output item that was marked done. - - `"text"` + - `output_index: number` - - `Grammar object { definition, syntax, type }` + The index of the output item that was marked done. - A grammar defined by the user. + - `sequence_number: number` - - `definition: string` + The sequence number of this event. - The grammar definition. + - `type: "response.output_item.done"` - - `syntax: "lark" or "regex"` + The type of the event. Always `response.output_item.done`. - The syntax of the grammar definition. One of `lark` or `regex`. + - `"response.output_item.done"` - - `"lark"` + - `agent: optional object { agent_name }` - - `"regex"` + The agent that owns this multi-agent streaming event. - - `type: "grammar"` + - `agent_name: string` - Grammar format. Always `grammar`. + The canonical name of the agent that produced this item. - - `"grammar"` + - `BetaResponseReasoningSummaryPartAddedEvent object { item_id, output_index, part, 4 more }` - - `type: "namespace"` + Emitted when a new reasoning summary part is added. - The type of the tool. Always `namespace`. + - `item_id: string` - - `"namespace"` + The ID of the item this summary part is associated with. - - `ToolSearch object { type, description, execution, parameters }` + - `output_index: number` - Hosted or BYOT tool search configuration for deferred tools. + The index of the output item this summary part is associated with. - - `type: "tool_search"` + - `part: object { text, type }` - The type of the tool. Always `tool_search`. + The summary part that was added. - - `"tool_search"` + - `text: string` - - `description: optional string` + The text of the summary part. - Description shown to the model for a client-executed tool search tool. + - `type: "summary_text"` - - `execution: optional "server" or "client"` + The type of the summary part. Always `summary_text`. - Whether tool search is executed by the server or by the client. + - `"summary_text"` - - `"server"` + - `sequence_number: number` - - `"client"` + The sequence number of this event. - - `parameters: optional unknown` + - `summary_index: number` - Parameter schema for a client-executed tool search tool. + The index of the summary part within the reasoning summary. - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `type: "response.reasoning_summary_part.added"` - 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 event. Always `response.reasoning_summary_part.added`. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `"response.reasoning_summary_part.added"` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `agent: optional object { agent_name }` - - `"web_search_preview"` + The agent that owns this multi-agent streaming event. - - `"web_search_preview_2025_03_11"` + - `agent_name: string` - - `search_content_types: optional array of "text" or "image"` + The canonical name of the agent that produced this item. - - `"text"` + - `BetaResponseReasoningSummaryPartDoneEvent object { item_id, output_index, part, 5 more }` - - `"image"` + Emitted when a reasoning summary part is completed. - - `search_context_size: optional "low" or "medium" or "high"` + - `item_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 this summary part is associated with. - - `"low"` + - `output_index: number` - - `"medium"` + The index of the output item this summary part is associated with. - - `"high"` + - `part: object { text, type }` - - `user_location: optional object { type, city, country, 2 more }` + The completed summary part. - The user's location. + - `text: string` - - `type: "approximate"` + The text of the summary part. - The type of location approximation. Always `approximate`. + - `type: "summary_text"` - - `"approximate"` + The type of the summary part. Always `summary_text`. - - `city: optional string` + - `"summary_text"` - Free text input for the city of the user, e.g. `San Francisco`. + - `sequence_number: number` + + The sequence number of this event. + + - `summary_index: number` + + The index of the summary part within the reasoning summary. + + - `type: "response.reasoning_summary_part.done"` + + The type of the event. Always `response.reasoning_summary_part.done`. - - `country: optional string` + - `"response.reasoning_summary_part.done"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `agent: optional object { agent_name }` - - `region: optional string` + The agent that owns this multi-agent streaming event. - Free text input for the region of the user, e.g. `California`. + - `agent_name: string` - - `timezone: optional string` + The canonical name of the agent that produced this item. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `status: optional "incomplete"` - - `ApplyPatch object { type, allowed_callers }` + The completion status of the summary part. Omitted when the part completed + normally and set to `incomplete` when generation was interrupted. - Allows the assistant to create, delete, or update files using unified diffs. + - `"incomplete"` - - `type: "apply_patch"` + - `BetaResponseReasoningSummaryTextDeltaEvent object { delta, item_id, output_index, 4 more }` - The type of the tool. Always `apply_patch`. + Emitted when a delta is added to a reasoning summary text. - - `"apply_patch"` + - `delta: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The text delta that was added to the summary. - The tool invocation context(s). + - `item_id: string` - - `"direct"` + The ID of the item this summary text delta is associated with. - - `"programmatic"` + - `output_index: number` - - `top_logprobs: optional number` + The index of the output item this summary text delta is associated with. - 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. + - `sequence_number: number` - - `top_p: optional number` + The sequence number of this event. - 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. + - `summary_index: number` - We generally recommend altering this or `temperature` but not both. + The index of the summary part within the reasoning summary. - - `truncation: optional "auto" or "disabled"` + - `type: "response.reasoning_summary_text.delta"` - The truncation strategy to use for the model response. + The type of the event. Always `response.reasoning_summary_text.delta`. - - `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. + - `"response.reasoning_summary_text.delta"` - - `"auto"` + - `agent: optional object { agent_name }` - - `"disabled"` + The agent that owns this multi-agent streaming event. - - `user: optional string` + - `agent_name: 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 canonical name of the agent that produced this item. - - `BetaResponseInjectEvent object { input, response_id, type }` + - `BetaResponseReasoningSummaryTextDoneEvent object { item_id, output_index, sequence_number, 4 more }` - Injects input items into an active response over a WebSocket connection. - The items are validated and committed atomically. Currently, the server - accepts client-owned tool outputs that resume a waiting agent. + Emitted when a reasoning summary text is completed. - - `input: array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + - `item_id: string` - Input items to inject into the active response. + The ID of the item this summary text is associated with. - - `BetaEasyInputMessage object { content, role, phase, type }` + - `output_index: number` - 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 index of the output item this summary text is associated with. - - `Message object { content, role, agent, 2 more }` + - `sequence_number: number` - 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. + The sequence number of this event. - - `content: BetaResponseInputMessageContentList` + - `summary_index: number` - A list of one or many input items to the model, containing different content - types. + The index of the summary part within the reasoning summary. - - `role: "user" or "system" or "developer"` + - `text: string` - The role of the message input. One of `user`, `system`, or `developer`. + The full text of the completed reasoning summary. - - `"user"` + - `type: "response.reasoning_summary_text.done"` - - `"system"` + The type of the event. Always `response.reasoning_summary_text.done`. - - `"developer"` + - `"response.reasoning_summary_text.done"` - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `BetaResponseReasoningTextDeltaEvent object { content_index, delta, item_id, 4 more }` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Emitted when a delta is added to a reasoning text. - - `"in_progress"` + - `content_index: number` - - `"completed"` + The index of the reasoning content part this delta is associated with. - - `"incomplete"` + - `delta: string` - - `type: optional "message"` + The text delta that was added to the reasoning content. - The type of the message input. Always set to `message`. + - `item_id: string` - - `"message"` + The ID of the item this reasoning text delta is associated with. - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + - `output_index: number` - An output message from the model. + The index of the output item this reasoning text delta is associated with. - - `FileSearchCall object { id, queries, status, 3 more }` + - `sequence_number: number` - The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + The sequence number of this event. - - `id: string` + - `type: "response.reasoning_text.delta"` - The unique ID of the file search tool call. + The type of the event. Always `response.reasoning_text.delta`. - - `queries: array of string` + - `"response.reasoning_text.delta"` - The queries used to search for files. + - `agent: optional object { agent_name }` - - `status: "in_progress" or "searching" or "completed" or 2 more` + The agent that owns this multi-agent streaming event. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `agent_name: string` - - `"in_progress"` + The canonical name of the agent that produced this item. - - `"searching"` + - `BetaResponseReasoningTextDoneEvent object { content_index, item_id, output_index, 4 more }` - - `"completed"` + Emitted when a reasoning text is completed. - - `"incomplete"` + - `content_index: number` - - `"failed"` + The index of the reasoning content part. - - `type: "file_search_call"` + - `item_id: string` - The type of the file search tool call. Always `file_search_call`. + The ID of the item this reasoning text is associated with. - - `"file_search_call"` + - `output_index: number` - - `agent: optional object { agent_name }` + The index of the output item this reasoning text is associated with. - The agent that produced this item. + - `sequence_number: number` - - `agent_name: string` + The sequence number of this event. - The canonical name of the agent that produced this item. + - `text: string` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + The full text of the completed reasoning content. - The results of the file search tool call. + - `type: "response.reasoning_text.done"` - - `attributes: optional map[string or number or boolean]` + The type of the event. Always `response.reasoning_text.done`. - 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. + - `"response.reasoning_text.done"` - - `string` + - `agent: optional object { agent_name }` - - `number` + The agent that owns this multi-agent streaming event. - - `boolean` + - `agent_name: string` - - `file_id: optional string` + The canonical name of the agent that produced this item. - The unique ID of the file. + - `BetaResponseRefusalDeltaEvent object { content_index, delta, item_id, 4 more }` - - `filename: optional string` + Emitted when there is a partial refusal text. - The name of the file. + - `content_index: number` - - `score: optional number` + The index of the content part that the refusal text is added to. - The relevance score of the file - a value between 0 and 1. + - `delta: string` - - `text: optional string` + The refusal text that is added. - The text that was retrieved from the file. + - `item_id: string` - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + The ID of the output item that the refusal text is added to. - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + - `output_index: number` - - `id: string` + The index of the output item that the refusal text is added to. - The unique ID of the computer call. + - `sequence_number: number` - - `call_id: string` + The sequence number of this event. - An identifier used when responding to the tool call with output. + - `type: "response.refusal.delta"` - - `pending_safety_checks: array of object { id, code, message }` + The type of the event. Always `response.refusal.delta`. - The pending safety checks for the computer call. + - `"response.refusal.delta"` - - `id: string` + - `agent: optional object { agent_name }` - The ID of the pending safety check. + The agent that owns this multi-agent streaming event. - - `code: optional string` + - `agent_name: string` - The type of the pending safety check. + The canonical name of the agent that produced this item. - - `message: optional string` + - `BetaResponseRefusalDoneEvent object { content_index, item_id, output_index, 4 more }` - Details about the pending safety check. + Emitted when refusal text is finalized. - - `status: "in_progress" or "completed" or "incomplete"` + - `content_index: number` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The index of the content part that the refusal text is finalized. - - `"in_progress"` + - `item_id: string` - - `"completed"` + The ID of the output item that the refusal text is finalized. - - `"incomplete"` + - `output_index: number` - - `type: "computer_call"` + The index of the output item that the refusal text is finalized. - The type of the computer call. Always `computer_call`. + - `refusal: string` - - `"computer_call"` + The refusal text that is finalized. - - `action: optional BetaComputerAction` + - `sequence_number: number` - A click action. + The sequence number of this event. - - `actions: optional BetaComputerActionList` + - `type: "response.refusal.done"` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + The type of the event. Always `response.refusal.done`. + + - `"response.refusal.done"` - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `ComputerCallOutput object { call_id, output, type, 4 more }` - - The output of a computer tool call. - - - `call_id: string` + - `BetaResponseTextDeltaEvent object { content_index, delta, item_id, 5 more }` - The ID of the computer tool call that produced the output. + Emitted when there is an additional text delta. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `content_index: number` - A computer screenshot image used with the computer use tool. + The index of the content part that the text delta was added to. - - `type: "computer_call_output"` + - `delta: string` - The type of the computer tool call output. Always `computer_call_output`. + The text delta that was added. - - `"computer_call_output"` + - `item_id: string` - - `id: optional string` + The ID of the output item that the text delta was added to. - The ID of the computer tool call output. + - `logprobs: array of object { token, logprob, top_logprobs }` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + The log probabilities of the tokens in the delta. - The safety checks reported by the API that have been acknowledged by the developer. + - `token: string` - - `id: string` + A possible text token. - The ID of the pending safety check. + - `logprob: number` - - `code: optional string` + The log probability of this token. - The type of the pending safety check. + - `top_logprobs: optional array of object { token, logprob }` - - `message: optional string` + The log probabilities of up to 20 of the most likely tokens. - Details about the pending safety check. + - `token: optional string` - - `agent: optional object { agent_name }` + A possible text token. - The agent that produced this item. + - `logprob: optional number` - - `agent_name: string` + The log probability of this token. - The canonical name of the agent that produced this item. + - `output_index: number` - - `status: optional "in_progress" or "completed" or "incomplete"` + The index of the output item that the text delta was added to. - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `sequence_number: number` - - `"in_progress"` + The sequence number for this event. - - `"completed"` + - `type: "response.output_text.delta"` - - `"incomplete"` + The type of the event. Always `response.output_text.delta`. - - `WebSearchCall object { id, action, status, 2 more }` + - `"response.output_text.delta"` - The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + - `agent: optional object { agent_name }` - - `id: string` + The agent that owns this multi-agent streaming event. - The unique ID of the web search tool call. + - `agent_name: string` - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + The canonical name of the agent that produced this item. - 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). + - `BetaResponseTextDoneEvent object { content_index, item_id, logprobs, 5 more }` - - `Search object { type, queries, query, sources }` + Emitted when text content is finalized. - Action type "search" - Performs a web search query. + - `content_index: number` - - `type: "search"` + The index of the content part that the text content is finalized. - The action type. + - `item_id: string` - - `"search"` + The ID of the output item that the text content is finalized. - - `queries: optional array of string` + - `logprobs: array of object { token, logprob, top_logprobs }` - The search queries. + The log probabilities of the tokens in the delta. - - `query: optional string` + - `token: string` - The search query. + A possible text token. - - `sources: optional array of object { type, url }` + - `logprob: number` - The sources used in the search. + The log probability of this token. - - `type: "url"` + - `top_logprobs: optional array of object { token, logprob }` - The type of source. Always `url`. + The log probabilities of up to 20 of the most likely tokens. - - `"url"` + - `token: optional string` - - `url: string` + A possible text token. - The URL of the source. + - `logprob: optional number` - - `OpenPage object { type, url }` + The log probability of this token. - Action type "open_page" - Opens a specific URL from search results. + - `output_index: number` - - `type: "open_page"` + The index of the output item that the text content is finalized. - The action type. + - `sequence_number: number` - - `"open_page"` + The sequence number for this event. - - `url: optional string` + - `text: string` - The URL opened by the model. + The text content that is finalized. - - `FindInPage object { pattern, type, url }` + - `type: "response.output_text.done"` - Action type "find_in_page": Searches for a pattern within a loaded page. + The type of the event. Always `response.output_text.done`. - - `pattern: string` + - `"response.output_text.done"` - The pattern or text to search for within the page. + - `agent: optional object { agent_name }` - - `type: "find_in_page"` + The agent that owns this multi-agent streaming event. - The action type. + - `agent_name: string` - - `"find_in_page"` + The canonical name of the agent that produced this item. - - `url: string` + - `BetaResponseWebSearchCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - The URL of the page searched for the pattern. + Emitted when a web search call is completed. - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `item_id: string` - The status of the web search tool call. + Unique ID for the output item associated with the web search call. - - `"in_progress"` + - `output_index: number` - - `"searching"` + The index of the output item that the web search call is associated with. - - `"completed"` + - `sequence_number: number` - - `"failed"` + The sequence number of the web search call being processed. - - `type: "web_search_call"` + - `type: "response.web_search_call.completed"` - The type of the web search tool call. Always `web_search_call`. + The type of the event. Always `response.web_search_call.completed`. - - `"web_search_call"` + - `"response.web_search_call.completed"` - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `FunctionCall object { arguments, call_id, name, 6 more }` - - A tool call to run a function. See the - [function calling guide](/docs/guides/function-calling) for more information. - - - `arguments: string` + - `BetaResponseWebSearchCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` - A JSON string of the arguments to pass to the function. + Emitted when a web search call is initiated. - - `call_id: string` + - `item_id: string` - The unique ID of the function tool call generated by the model. + Unique ID for the output item associated with the web search call. - - `name: string` + - `output_index: number` - The name of the function to run. + The index of the output item that the web search call is associated with. - - `type: "function_call"` + - `sequence_number: number` - The type of the function tool call. Always `function_call`. + The sequence number of the web search call being processed. - - `"function_call"` + - `type: "response.web_search_call.in_progress"` - - `id: optional string` + The type of the event. Always `response.web_search_call.in_progress`. - The unique ID of the function tool call. + - `"response.web_search_call.in_progress"` - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` + - `BetaResponseWebSearchCallSearchingEvent object { item_id, output_index, sequence_number, 2 more }` - The execution context that produced this tool call. + Emitted when a web search call is executing. - - `Direct object { type }` + - `item_id: string` - - `type: "direct"` + Unique ID for the output item associated with the web search call. - - `"direct"` + - `output_index: number` - - `Program object { caller_id, type }` + The index of the output item that the web search call is associated with. - - `caller_id: string` + - `sequence_number: number` - The call ID of the program item that produced this tool call. + The sequence number of the web search call being processed. - - `type: "program"` + - `type: "response.web_search_call.searching"` - - `"program"` + The type of the event. Always `response.web_search_call.searching`. - - `namespace: optional string` + - `"response.web_search_call.searching"` - The namespace of the function to run. + - `agent: optional object { agent_name }` - - `status: optional "in_progress" or "completed" or "incomplete"` + The agent that owns this multi-agent streaming event. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `agent_name: string` - - `"in_progress"` + The canonical name of the agent that produced this item. - - `"completed"` + - `BetaResponseImageGenCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - - `"incomplete"` + Emitted when an image generation tool call has completed and the final image is available. - - `FunctionCallOutput object { call_id, output, type, 4 more }` + - `item_id: string` - The output of a function tool call. + The unique identifier of the image generation item being processed. - - `call_id: string` + - `output_index: number` - The unique ID of the function tool call generated by the model. + The index of the output item in the response's output array. - - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` + - `sequence_number: number` - Text, image, or file output of the function tool call. + The sequence number of this event. - - `string` + - `type: "response.image_generation_call.completed"` - A JSON string of the output of the function tool call. + The type of the event. Always 'response.image_generation_call.completed'. - - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` + - `"response.image_generation_call.completed"` - An array of content outputs (text, image, file) for the function tool call. + - `agent: optional object { agent_name }` - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + The agent that owns this multi-agent streaming event. - A text input to the model. + - `agent_name: string` - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + The canonical name of the agent that produced this item. - An image input to the model. Learn about [image inputs](/docs/guides/vision) + - `BetaResponseImageGenCallGeneratingEvent object { item_id, output_index, sequence_number, 2 more }` - - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` + Emitted when an image generation tool call is actively generating an image (intermediate state). - A file input to the model. + - `item_id: string` - - `type: "function_call_output"` + The unique identifier of the image generation item being processed. - The type of the function tool call output. Always `function_call_output`. + - `output_index: number` - - `"function_call_output"` + The index of the output item in the response's output array. - - `id: optional string` + - `sequence_number: number` - The unique ID of the function tool call output. Populated when this item is returned via API. + The sequence number of the image generation item being processed. + + - `type: "response.image_generation_call.generating"` + + The type of the event. Always 'response.image_generation_call.generating'. + + - `"response.image_generation_call.generating"` - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. + - `BetaResponseImageGenCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` - - `Direct object { type }` + Emitted when an image generation tool call is in progress. - - `type: "direct"` + - `item_id: string` - The caller type. Always `direct`. + The unique identifier of the image generation item being processed. - - `"direct"` + - `output_index: number` - - `Program object { caller_id, type }` + The index of the output item in the response's output array. - - `caller_id: string` + - `sequence_number: number` - The call ID of the program item that produced this tool call. + The sequence number of the image generation item being processed. - - `type: "program"` + - `type: "response.image_generation_call.in_progress"` - The caller type. Always `program`. + The type of the event. Always 'response.image_generation_call.in_progress'. - - `"program"` + - `"response.image_generation_call.in_progress"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `agent: optional object { agent_name }` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + The agent that owns this multi-agent streaming event. - - `"in_progress"` + - `agent_name: string` - - `"completed"` + The canonical name of the agent that produced this item. - - `"incomplete"` + - `BetaResponseImageGenCallPartialImageEvent object { item_id, output_index, partial_image_b64, 4 more }` - - `AgentMessage object { author, content, recipient, 3 more }` + Emitted when a partial image is available during image generation streaming. - A message routed between agents. + - `item_id: string` - - `author: string` + The unique identifier of the image generation item being processed. - The sending agent identity. + - `output_index: number` - - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` + The index of the output item in the response's output array. - Plaintext, image, or encrypted content sent between agents. + - `partial_image_b64: string` - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + Base64-encoded partial image data, suitable for rendering as an image. - A text input to the model. + - `partial_image_index: number` - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). - An image input to the model. Learn about [image inputs](/docs/guides/vision) + - `sequence_number: number` - - `EncryptedContent object { encrypted_content, type }` + The sequence number of the image generation item being processed. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `type: "response.image_generation_call.partial_image"` - - `encrypted_content: string` + The type of the event. Always 'response.image_generation_call.partial_image'. - Opaque encrypted content. + - `"response.image_generation_call.partial_image"` - - `type: "encrypted_content"` + - `agent: optional object { agent_name }` - The type of the input item. Always `encrypted_content`. + The agent that owns this multi-agent streaming event. - - `"encrypted_content"` + - `agent_name: string` - - `recipient: string` + The canonical name of the agent that produced this item. - The destination agent identity. + - `BetaResponseMcpCallArgumentsDeltaEvent object { delta, item_id, output_index, 3 more }` - - `type: "agent_message"` + Emitted when there is a delta (partial update) to the arguments of an MCP tool call. - The item type. Always `agent_message`. + - `delta: string` - - `"agent_message"` + A JSON string containing the partial update to the arguments for the MCP tool call. - - `id: optional string` + - `item_id: string` - The unique ID of this agent message item. + The unique identifier of the MCP tool call item being processed. - - `agent: optional object { agent_name }` + - `output_index: number` - The agent that produced this item. + The index of the output item in the response's output array. - - `agent_name: string` + - `sequence_number: number` - The canonical name of the agent that produced this item. + The sequence number of this event. - - `MultiAgentCall object { action, arguments, call_id, 3 more }` + - `type: "response.mcp_call_arguments.delta"` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + The type of the event. Always 'response.mcp_call_arguments.delta'. - The multi-agent action that was executed. + - `"response.mcp_call_arguments.delta"` - - `"spawn_agent"` + - `agent: optional object { agent_name }` - - `"interrupt_agent"` + The agent that owns this multi-agent streaming event. - - `"list_agents"` + - `agent_name: string` - - `"send_message"` + The canonical name of the agent that produced this item. - - `"followup_task"` + - `BetaResponseMcpCallArgumentsDoneEvent object { arguments, item_id, output_index, 3 more }` - - `"wait_agent"` + Emitted when the arguments for an MCP tool call are finalized. - `arguments: string` - The action arguments as a JSON string. + A JSON string containing the finalized arguments for the MCP tool call. - - `call_id: string` + - `item_id: string` - The unique ID linking this call to its output. + The unique identifier of the MCP tool call item being processed. - - `type: "multi_agent_call"` + - `output_index: number` - The item type. Always `multi_agent_call`. + The index of the output item in the response's output array. - - `"multi_agent_call"` + - `sequence_number: number` - - `id: optional string` + The sequence number of this event. - The unique ID of this multi-agent call. + - `type: "response.mcp_call_arguments.done"` + + The type of the event. Always 'response.mcp_call_arguments.done'. + + - `"response.mcp_call_arguments.done"` - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `MultiAgentCallOutput object { action, call_id, output, 3 more }` - - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - The multi-agent action that produced this result. - - - `"spawn_agent"` - - - `"interrupt_agent"` - - - `"list_agents"` + - `BetaResponseMcpCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - - `"send_message"` + Emitted when an MCP tool call has completed successfully. - - `"followup_task"` + - `item_id: string` - - `"wait_agent"` + The ID of the MCP tool call item that completed. - - `call_id: string` + - `output_index: number` - The unique ID of the multi-agent call. + The index of the output item that completed. - - `output: array of object { text, type, annotations }` + - `sequence_number: number` - Text output returned by the multi-agent action. + The sequence number of this event. - - `text: string` + - `type: "response.mcp_call.completed"` - The text content. + The type of the event. Always 'response.mcp_call.completed'. - - `type: "output_text"` + - `"response.mcp_call.completed"` - The content type. Always `output_text`. + - `agent: optional object { agent_name }` - - `"output_text"` + The agent that owns this multi-agent streaming event. - - `annotations: optional 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 }` + - `agent_name: string` - Citations associated with the text content. + The canonical name of the agent that produced this item. - - `FileCitation object { file_id, filename, index, type }` + - `BetaResponseMcpCallFailedEvent object { item_id, output_index, sequence_number, 2 more }` - - `file_id: string` + Emitted when an MCP tool call has failed. - The ID of the file. + - `item_id: string` - - `filename: string` + The ID of the MCP tool call item that failed. - The filename of the file cited. + - `output_index: number` - - `index: number` + The index of the output item that failed. - The index of the file in the list of files. + - `sequence_number: number` - - `type: "file_citation"` + The sequence number of this event. - The citation type. Always `file_citation`. + - `type: "response.mcp_call.failed"` - - `"file_citation"` + The type of the event. Always 'response.mcp_call.failed'. - - `URLCitation object { end_index, start_index, title, 2 more }` + - `"response.mcp_call.failed"` - - `end_index: number` + - `agent: optional object { agent_name }` - The index of the last character of the citation in the message. + The agent that owns this multi-agent streaming event. - - `start_index: number` + - `agent_name: string` - The index of the first character of the citation in the message. + The canonical name of the agent that produced this item. - - `title: string` + - `BetaResponseMcpCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` - The title of the cited resource. + Emitted when an MCP tool call is in progress. - - `type: "url_citation"` + - `item_id: string` - The citation type. Always `url_citation`. + The unique identifier of the MCP tool call item being processed. - - `"url_citation"` + - `output_index: number` - - `url: string` + The index of the output item in the response's output array. - The URL of the cited resource. + - `sequence_number: number` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + The sequence number of this event. - - `container_id: string` + - `type: "response.mcp_call.in_progress"` - The ID of the container. + The type of the event. Always 'response.mcp_call.in_progress'. - - `end_index: number` + - `"response.mcp_call.in_progress"` - The index of the last character of the citation in the message. + - `agent: optional object { agent_name }` - - `file_id: string` + The agent that owns this multi-agent streaming event. - The ID of the container file. + - `agent_name: string` - - `filename: string` + The canonical name of the agent that produced this item. - The filename of the container file cited. + - `BetaResponseMcpListToolsCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - - `start_index: number` + Emitted when the list of available MCP tools has been successfully retrieved. - The index of the first character of the citation in the message. + - `item_id: string` - - `type: "container_file_citation"` + The ID of the MCP tool call item that produced this output. - The citation type. Always `container_file_citation`. + - `output_index: number` - - `"container_file_citation"` + The index of the output item that was processed. - - `type: "multi_agent_call_output"` + - `sequence_number: number` - The item type. Always `multi_agent_call_output`. + The sequence number of this event. - - `"multi_agent_call_output"` + - `type: "response.mcp_list_tools.completed"` - - `id: optional string` + The type of the event. Always 'response.mcp_list_tools.completed'. - The unique ID of this multi-agent call output. + - `"response.mcp_list_tools.completed"` - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `ToolSearchCall object { arguments, type, id, 4 more }` + - `BetaResponseMcpListToolsFailedEvent object { item_id, output_index, sequence_number, 2 more }` - - `arguments: unknown` + Emitted when the attempt to list available MCP tools has failed. - The arguments supplied to the tool search call. + - `item_id: string` - - `type: "tool_search_call"` + The ID of the MCP tool call item that failed. - The item type. Always `tool_search_call`. + - `output_index: number` - - `"tool_search_call"` + The index of the output item that failed. - - `id: optional string` + - `sequence_number: number` - The unique ID of this tool search call. + The sequence number of this event. + + - `type: "response.mcp_list_tools.failed"` + + The type of the event. Always 'response.mcp_list_tools.failed'. + + - `"response.mcp_list_tools.failed"` - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `call_id: optional string` + - `BetaResponseMcpListToolsInProgressEvent object { item_id, output_index, sequence_number, 2 more }` - The unique ID of the tool search call generated by the model. + Emitted when the system is in the process of retrieving the list of available MCP tools. - - `execution: optional "server" or "client"` + - `item_id: string` - Whether tool search was executed by the server or by the client. + The ID of the MCP tool call item that is being processed. - - `"server"` + - `output_index: number` - - `"client"` + The index of the output item that is being processed. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `sequence_number: number` - The status of the tool search call. + The sequence number of this event. - - `"in_progress"` + - `type: "response.mcp_list_tools.in_progress"` - - `"completed"` + The type of the event. Always 'response.mcp_list_tools.in_progress'. - - `"incomplete"` + - `"response.mcp_list_tools.in_progress"` - - `ToolSearchOutput object { tools, type, id, 4 more }` + - `agent: optional object { agent_name }` - - `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 agent that owns this multi-agent streaming event. - The loaded tool definitions returned by the tool search output. + - `agent_name: string` - - `Function object { name, parameters, strict, 5 more }` + The canonical name of the agent that produced this item. - 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). + - `BetaResponseOutputTextAnnotationAddedEvent object { annotation, annotation_index, content_index, 5 more }` - - `name: string` + Emitted when an annotation is added to output text content. - The name of the function to call. + - `annotation: unknown` - - `parameters: map[unknown]` + The annotation object being added. (See annotation schema for details.) - A JSON schema object describing the parameters of the function. + - `annotation_index: number` - - `strict: boolean` + The index of the annotation within the content part. - Whether strict parameter validation is enforced for this function tool. + - `content_index: number` - - `type: "function"` + The index of the content part within the output item. - The type of the function tool. Always `function`. + - `item_id: string` - - `"function"` + The unique identifier of the item to which the annotation is being added. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `output_index: number` - The tool invocation context(s). + The index of the output item in the response's output array. - - `"direct"` + - `sequence_number: number` - - `"programmatic"` + The sequence number of this event. - - `defer_loading: optional boolean` + - `type: "response.output_text.annotation.added"` - Whether this function is deferred and loaded via tool search. + The type of the event. Always 'response.output_text.annotation.added'. - - `description: optional string` + - `"response.output_text.annotation.added"` - A description of the function. Used by the model to determine whether or not to call the function. + - `agent: optional object { agent_name }` - - `output_schema: optional map[unknown]` + The agent that owns this multi-agent streaming event. - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `agent_name: string` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + The canonical name of the agent that produced this item. - 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). + - `BetaResponseQueuedEvent object { response, sequence_number, type, agent }` - - `type: "file_search"` + Emitted when a response is queued and waiting to be processed. - The type of the file search tool. Always `file_search`. + - `response: BetaResponse` - - `"file_search"` + The full response object that is queued. - - `vector_store_ids: array of string` + - `sequence_number: number` - The IDs of the vector stores to search. + The sequence number for this event. - - `filters: optional object { key, type, value } or object { filters, type }` + - `type: "response.queued"` - A filter to apply. + The type of the event. Always 'response.queued'. - - `ComparisonFilter object { key, type, value }` + - `"response.queued"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `agent: optional object { agent_name }` - - `key: string` + The agent that owns this multi-agent streaming event. - The key to compare against the value. + - `agent_name: string` - - `type: "eq" or "ne" or "gt" or 5 more` + The canonical name of the agent that produced this item. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `BetaResponseCustomToolCallInputDeltaEvent object { delta, item_id, output_index, 3 more }` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + Event representing a delta (partial update) to the input of a custom tool call. - - `"eq"` + - `delta: string` - - `"ne"` + The incremental input data (delta) for the custom tool call. - - `"gt"` + - `item_id: string` - - `"gte"` + Unique identifier for the API item associated with this event. - - `"lt"` + - `output_index: number` - - `"lte"` + The index of the output this delta applies to. - - `"in"` + - `sequence_number: number` - - `"nin"` + The sequence number of this event. - - `value: string or number or boolean or array of string or number` + - `type: "response.custom_tool_call_input.delta"` - The value to compare against the attribute key; supports string, number, or boolean types. + The event type identifier. - - `string` + - `"response.custom_tool_call_input.delta"` - - `number` + - `agent: optional object { agent_name }` - - `boolean` + The agent that owns this multi-agent streaming event. - - `array of string or number` + - `agent_name: string` - - `string` + The canonical name of the agent that produced this item. - - `number` + - `BetaResponseCustomToolCallInputDoneEvent object { input, item_id, output_index, 3 more }` - - `CompoundFilter object { filters, type }` + Event indicating that input for a custom tool call is complete. - Combine multiple filters using `and` or `or`. + - `input: string` - - `filters: array of object { key, type, value } or unknown` + The complete input data for the custom tool call. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `item_id: string` - - `ComparisonFilter object { key, type, value }` + Unique identifier for the API item associated with this event. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `output_index: number` - - `key: string` + The index of the output this event applies to. - The key to compare against the value. + - `sequence_number: number` - - `type: "eq" or "ne" or "gt" or 5 more` + The sequence number of this event. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `type: "response.custom_tool_call_input.done"` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + The event type identifier. - - `"eq"` + - `"response.custom_tool_call_input.done"` - - `"ne"` + - `agent: optional object { agent_name }` - - `"gt"` + The agent that owns this multi-agent streaming event. - - `"gte"` + - `agent_name: string` - - `"lt"` + The canonical name of the agent that produced this item. - - `"lte"` +### Beta Response Text Config - - `"in"` +- `BetaResponseTextConfig object { format, verbosity }` - - `"nin"` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - - `value: string or number or boolean or array of string or number` + - [Text inputs and outputs](/docs/guides/text) + - [Structured Outputs](/docs/guides/structured-outputs) - The value to compare against the attribute key; supports string, number, or boolean types. + - `format: optional BetaResponseFormatTextConfig` + + 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. + + - `Text object { type }` + + Default response format. Used to generate text responses. + + - `type: "text"` + + The type of response format being defined. Always `text`. - - `string` + - `"text"` - - `number` + - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` - - `boolean` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `array of string or number` + - `name: string` - - `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. - - `number` + - `schema: map[unknown]` - - `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: "and" or "or"` + - `type: "json_schema"` - Type of operation: `and` or `or`. + The type of response format being defined. Always `json_schema`. - - `"and"` + - `"json_schema"` - - `"or"` + - `description: optional string` - - `max_num_results: optional number` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `strict: optional boolean` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + 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). - Ranking options for search. + - `JSONObject object { type }` - - `hybrid_search: optional object { embedding_weight, text_weight }` + 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. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `type: "json_object"` - - `embedding_weight: number` + The type of response format being defined. Always `json_object`. - The weight of the embedding in the reciprocal ranking fusion. + - `"json_object"` - - `text_weight: number` + - `verbosity: optional "low" or "medium" or "high"` - The weight of the text in the reciprocal ranking fusion. + 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`. - - `ranker: optional "auto" or "default-2024-11-15"` + - `"low"` - The ranker to use for the file search. + - `"medium"` - - `"auto"` + - `"high"` - - `"default-2024-11-15"` +### Beta Response Text Delta Event - - `score_threshold: optional number` +- `BetaResponseTextDeltaEvent object { content_index, delta, item_id, 5 more }` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + Emitted when there is an additional text delta. - - `Computer object { type }` + - `content_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 content part that the text delta was added to. - - `type: "computer"` + - `delta: string` - The type of the computer tool. Always `computer`. + The text delta that was added. - - `"computer"` + - `item_id: string` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + The ID of the output item that the text delta was added to. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `logprobs: array of object { token, logprob, top_logprobs }` - - `display_height: number` + The log probabilities of the tokens in the delta. - The height of the computer display. + - `token: string` - - `display_width: number` + A possible text token. - The width of the computer display. + - `logprob: number` - - `environment: "windows" or "mac" or "linux" or 2 more` + The log probability of this token. - The type of computer environment to control. + - `top_logprobs: optional array of object { token, logprob }` - - `"windows"` + The log probabilities of up to 20 of the most likely tokens. - - `"mac"` + - `token: optional string` - - `"linux"` + A possible text token. - - `"ubuntu"` + - `logprob: optional number` - - `"browser"` + The log probability of this token. - - `type: "computer_use_preview"` + - `output_index: number` - The type of the computer use tool. Always `computer_use_preview`. + The index of the output item that the text delta was added to. - - `"computer_use_preview"` + - `sequence_number: number` - - `WebSearch object { type, filters, search_context_size, user_location }` + The sequence number for this event. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + - `type: "response.output_text.delta"` - - `type: "web_search" or "web_search_2025_08_26"` + The type of the event. Always `response.output_text.delta`. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `"response.output_text.delta"` - - `"web_search"` + - `agent: optional object { agent_name }` - - `"web_search_2025_08_26"` + The agent that owns this multi-agent streaming event. - - `filters: optional object { allowed_domains }` + - `agent_name: string` - Filters for the search. + The canonical name of the agent that produced this item. - - `allowed_domains: optional array of string` +### Beta Response Text Done Event - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. +- `BetaResponseTextDoneEvent object { content_index, item_id, logprobs, 5 more }` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + Emitted when text content is finalized. - - `search_context_size: optional "low" or "medium" or "high"` + - `content_index: number` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The index of the content part that the text content is finalized. - - `"low"` + - `item_id: string` - - `"medium"` + The ID of the output item that the text content is finalized. - - `"high"` + - `logprobs: array of object { token, logprob, top_logprobs }` - - `user_location: optional object { city, country, region, 2 more }` + The log probabilities of the tokens in the delta. - The approximate location of the user. + - `token: string` - - `city: optional string` + A possible text token. - Free text input for the city of the user, e.g. `San Francisco`. + - `logprob: number` - - `country: optional string` + The log probability of this token. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `top_logprobs: optional array of object { token, logprob }` - - `region: optional string` + The log probabilities of up to 20 of the most likely tokens. - Free text input for the region of the user, e.g. `California`. + - `token: optional string` - - `timezone: optional string` + A possible text token. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `logprob: optional number` - - `type: optional "approximate"` + The log probability of this token. - The type of location approximation. Always `approximate`. + - `output_index: number` - - `"approximate"` + The index of the output item that the text content is finalized. - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `sequence_number: number` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + The sequence number for this event. - - `server_label: string` + - `text: string` - A label for this MCP server, used to identify it in tool calls. + The text content that is finalized. - - `type: "mcp"` + - `type: "response.output_text.done"` - The type of the MCP tool. Always `mcp`. + The type of the event. Always `response.output_text.done`. - - `"mcp"` + - `"response.output_text.done"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `agent: optional object { agent_name }` - The tool invocation context(s). + The agent that owns this multi-agent streaming event. - - `"direct"` + - `agent_name: string` - - `"programmatic"` + The canonical name of the agent that produced this item. - - `allowed_tools: optional array of string or object { read_only, tool_names }` +### Beta Response Usage - List of allowed tool names or a filter object. +- `BetaResponseUsage object { input_tokens, input_tokens_details, output_tokens, 2 more }` - - `McpAllowedTools = array of string` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - A string array of allowed tool names + - `input_tokens: number` - - `McpToolFilter object { read_only, tool_names }` + The number of input tokens. - A filter object to specify which tools are allowed. + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` - - `read_only: optional boolean` + A detailed breakdown of the input 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. + - `cache_write_tokens: number` - - `tool_names: optional array of string` + The number of input tokens that were written to the cache. - List of allowed tool names. + - `cached_tokens: number` - - `authorization: optional string` + The number of tokens that were retrieved from the cache. + [More on prompt caching](/docs/guides/prompt-caching). - 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. + - `output_tokens: number` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + The number of output tokens. - 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). + - `output_tokens_details: object { reasoning_tokens }` - Currently supported `connector_id` values are: + A detailed breakdown of the output tokens. - - 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` + - `reasoning_tokens: number` - - `"connector_dropbox"` + The number of reasoning tokens. - - `"connector_gmail"` + - `total_tokens: number` - - `"connector_googlecalendar"` + The total number of tokens used. - - `"connector_googledrive"` +### Beta Response Web Search Call Completed Event - - `"connector_microsoftteams"` +- `BetaResponseWebSearchCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - - `"connector_outlookcalendar"` + Emitted when a web search call is completed. - - `"connector_outlookemail"` + - `item_id: string` - - `"connector_sharepoint"` + Unique ID for the output item associated with the web search call. - - `defer_loading: optional boolean` + - `output_index: number` - Whether this MCP tool is deferred and discovered via tool search. + The index of the output item that the web search call is associated with. - - `headers: optional map[string]` + - `sequence_number: number` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The sequence number of the web search call being processed. - - `require_approval: optional object { always, never } or "always" or "never"` + - `type: "response.web_search_call.completed"` - Specify which of the MCP server's tools require approval. + The type of the event. Always `response.web_search_call.completed`. - - `McpToolApprovalFilter object { always, never }` + - `"response.web_search_call.completed"` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `agent: optional object { agent_name }` - - `always: optional object { read_only, tool_names }` + The agent that owns this multi-agent streaming event. - A filter object to specify which tools are allowed. + - `agent_name: string` - - `read_only: optional boolean` + The canonical name of the agent that produced this item. - 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. +### Beta Response Web Search Call In Progress Event - - `tool_names: optional array of string` +- `BetaResponseWebSearchCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` - List of allowed tool names. + Emitted when a web search call is initiated. - - `never: optional object { read_only, tool_names }` + - `item_id: string` - A filter object to specify which tools are allowed. + Unique ID for the output item associated with the web search call. - - `read_only: optional boolean` + - `output_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 output item that the web search call is associated with. - - `tool_names: optional array of string` + - `sequence_number: number` - List of allowed tool names. + The sequence number of the web search call being processed. - - `McpToolApprovalSetting = "always" or "never"` + - `type: "response.web_search_call.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 type of the event. Always `response.web_search_call.in_progress`. - - `"always"` + - `"response.web_search_call.in_progress"` - - `"never"` + - `agent: optional object { agent_name }` - - `server_description: optional string` + The agent that owns this multi-agent streaming event. - Optional description of the MCP server, used to provide more context. + - `agent_name: string` - - `server_url: optional string` + The canonical name of the agent that produced this item. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. +### Beta Response Web Search Call Searching Event - - `tunnel_id: optional string` +- `BetaResponseWebSearchCallSearchingEvent object { item_id, output_index, sequence_number, 2 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. + Emitted when a web search call is executing. - - `CodeInterpreter object { container, type, allowed_callers }` + - `item_id: string` - A tool that runs Python code to help generate a response to a prompt. + Unique ID for the output item associated with the web search call. - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `output_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 output item that the web search call is associated with. - - `string` + - `sequence_number: number` - The container ID. + The sequence number of the web search call being processed. - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `type: "response.web_search_call.searching"` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + The type of the event. Always `response.web_search_call.searching`. - - `type: "auto"` + - `"response.web_search_call.searching"` - Always `auto`. + - `agent: optional object { agent_name }` - - `"auto"` + The agent that owns this multi-agent streaming event. - - `file_ids: optional array of string` + - `agent_name: string` - An optional list of uploaded files to make available to your code. + The canonical name of the agent that produced this item. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` +### Beta Responses Client Event - The memory limit for the code interpreter container. +- `BetaResponsesClientEvent = object { type, background, context_management, 30 more } or BetaResponseInjectEvent` - - `"1g"` + Client events accepted by the Responses WebSocket server. - - `"4g"` + - `ResponseCreate object { type, background, context_management, 30 more }` - - `"16g"` + Client event for creating a response over a persistent WebSocket connection. + This payload uses the same top-level fields as `POST /v1/responses`. - - `"64g"` + Notes: - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `stream` is implicit over WebSocket and should not be sent. + - `background` is not supported over WebSocket. - Network access policy for the container. + - `type: "response.create"` - - `BetaContainerNetworkPolicyDisabled object { type }` + The type of the client event. Always `response.create`. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `"response.create"` - - `type: "code_interpreter"` + - `background: optional boolean` - The type of the code interpreter tool. Always `code_interpreter`. + Whether to run the model response in the background. + [Learn more](/docs/guides/background). - - `"code_interpreter"` + - `context_management: optional array of object { type, compact_threshold }` - - `allowed_callers: optional array of "direct" or "programmatic"` + Context management configuration for this request. - The tool invocation context(s). + - `type: string` - - `"direct"` + The context management entry type. Currently only 'compaction' is supported. - - `"programmatic"` + - `compact_threshold: optional number` - - `ProgrammaticToolCalling object { type }` + Token threshold at which compaction should be triggered for this entry. - - `type: "programmatic_tool_calling"` + - `conversation: optional string or BetaResponseConversationParam` - The type of the tool. Always `programmatic_tool_calling`. + 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. - - `"programmatic_tool_calling"` + - `ConversationID = string` - - `ImageGeneration object { type, action, background, 9 more }` + The unique ID of the conversation. - A tool that generates images using the GPT image models. + - `BetaResponseConversationParam object { id }` - - `type: "image_generation"` + The conversation that this response belongs to. - The type of the image generation tool. Always `image_generation`. + - `id: string` - - `"image_generation"` + The unique ID of the conversation. - - `action: optional "generate" or "edit" or "auto"` + - `include: optional array of BetaResponseIncludable` - Whether to generate a new image or edit an existing image. Default: `auto`. + Specify additional output data to include in the model response. Currently supported values are: - - `"generate"` + - `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). - - `"edit"` + - `"file_search_call.results"` - - `"auto"` + - `"web_search_call.results"` - - `background: optional "transparent" or "opaque" or "auto"` + - `"web_search_call.action.sources"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + - `"message.input_image.image_url"` - - `"transparent"` + - `"computer_call_output.output.image_url"` - - `"opaque"` + - `"code_interpreter_call.outputs"` - - `"auto"` + - `"reasoning.encrypted_content"` - - `input_fidelity: optional "high" or "low"` + - `"message.output_text.logprobs"` - 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`. + - `input: optional string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - - `"high"` + Text, image, or file inputs to the model, used to generate a response. - - `"low"` + Learn more: - - `input_image_mask: optional object { file_id, image_url }` + - [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) - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `TextInput = string` - - `file_id: optional string` + A text input to the model, equivalent to a text input with the + `user` role. - File ID for the mask image. + - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - - `image_url: optional string` + A list of one or many input items to the model, containing + different content types. - Base64-encoded mask image. + - `BetaEasyInputMessage object { content, role, phase, type }` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + 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 image generation model to use. Default: `gpt-image-1`. + - `content: string or BetaResponseInputMessageContentList` - - `string` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `TextInput = string` - The image generation model to use. Default: `gpt-image-1`. + A text input to the model. - - `"gpt-image-1"` + - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` - - `"gpt-image-1-mini"` + A list of one or many input items to the model, containing different content + types. - - `"gpt-image-1.5"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `moderation: optional "auto" or "low"` + A text input to the model. - Moderation level for the generated image. Default: `auto`. + - `text: string` - - `"auto"` + The text input to the model. - - `"low"` + - `type: "input_text"` - - `output_compression: optional number` + The type of the input item. Always `input_text`. - Compression level for the output image. Default: 100. + - `"input_text"` - - `output_format: optional "png" or "webp" or "jpeg"` + - `prompt_cache_breakpoint: optional object { mode }` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + 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. - - `"png"` + - `mode: "explicit"` - - `"webp"` + The breakpoint mode. Always `explicit`. - - `"jpeg"` + - `"explicit"` - - `partial_images: optional number` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `quality: optional "low" or "medium" or "high" or "auto"` + - `detail: "low" or "high" or "auto" or "original"` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `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"` + - `"original"` - 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: "input_image"` - - `"1024x1024"` + The type of the input item. Always `input_image`. - - `"1024x1536"` + - `"input_image"` - - `"1536x1024"` + - `file_id: optional string` - - `"auto"` + The ID of the file to be sent to the model. - - `LocalShell object { type }` + - `image_url: optional string` - A tool that allows the model to execute shell commands in a local environment. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `type: "local_shell"` + - `prompt_cache_breakpoint: optional object { mode }` - The type of the local shell tool. Always `local_shell`. + 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. - - `"local_shell"` + - `mode: "explicit"` - - `Shell object { type, allowed_callers, environment }` + The breakpoint mode. Always `explicit`. - A tool that allows the model to execute shell commands. + - `"explicit"` - - `type: "shell"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - The type of the shell tool. Always `shell`. + A file input to the model. - - `"shell"` + - `type: "input_file"` - - `allowed_callers: optional array of "direct" or "programmatic"` + The type of the input item. Always `input_file`. - The tool invocation context(s). + - `"input_file"` - - `"direct"` + - `detail: optional "auto" or "low" or "high"` - - `"programmatic"` + 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`. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `"auto"` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `"low"` - - `BetaLocalEnvironment object { type, skills }` + - `"high"` - - `BetaContainerReference object { container_id, type }` + - `file_data: optional string` - - `Custom object { name, type, allowed_callers, 3 more }` + The content of the file to be sent to the model. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `file_id: optional string` - - `name: string` + The ID of the file to be sent to the model. - The name of the custom tool, used to identify it in tool calls. + - `file_url: optional string` - - `type: "custom"` + The URL of the file to be sent to the model. - The type of the custom tool. Always `custom`. + - `filename: optional string` - - `"custom"` + The name of the file to be sent to the model. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `prompt_cache_breakpoint: optional object { mode }` - The tool invocation context(s). + 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. - - `"direct"` + - `mode: "explicit"` - - `"programmatic"` + The breakpoint mode. Always `explicit`. - - `defer_loading: optional boolean` + - `"explicit"` - Whether this tool should be deferred and discovered via tool search. + - `role: "user" or "assistant" or "system" or "developer"` - - `description: optional string` + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - Optional description of the custom tool, used to provide more context. + - `"user"` - - `format: optional object { type } or object { definition, syntax, type }` + - `"assistant"` - The input format for the custom tool. Default is unconstrained text. + - `"system"` - - `Text object { type }` + - `"developer"` - Unconstrained free-form text. + - `phase: optional "commentary" or "final_answer"` - - `type: "text"` + Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). + For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend + phase on all assistant messages — dropping it can degrade performance. Not used for user messages. - Unconstrained text format. Always `text`. + - `"commentary"` - - `"text"` + - `"final_answer"` - - `Grammar object { definition, syntax, type }` + - `type: optional "message"` - A grammar defined by the user. + The type of the message input. Always `message`. - - `definition: string` + - `"message"` - The grammar definition. + - `Message object { content, role, agent, 2 more }` - - `syntax: "lark" or "regex"` + 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. - The syntax of the grammar definition. One of `lark` or `regex`. + - `content: BetaResponseInputMessageContentList` - - `"lark"` + A list of one or many input items to the model, containing different content + types. - - `"regex"` + - `role: "user" or "system" or "developer"` - - `type: "grammar"` + The role of the message input. One of `user`, `system`, or `developer`. - Grammar format. Always `grammar`. + - `"user"` - - `"grammar"` + - `"system"` - - `Namespace object { description, name, tools, type }` + - `"developer"` - Groups function/custom tools under a shared namespace. + - `agent: optional object { agent_name }` - - `description: string` + The agent that produced this item. - A description of the namespace shown to the model. + - `agent_name: string` - - `name: string` + The canonical name of the agent that produced this item. - The namespace name used in tool calls (for example, `crm`). + - `status: optional "in_progress" or "completed" or "incomplete"` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The function/custom tools available inside this namespace. + - `"in_progress"` - - `Function object { name, type, allowed_callers, 5 more }` + - `"completed"` - - `name: string` + - `"incomplete"` - - `type: "function"` + - `type: optional "message"` - - `"function"` + The type of the message input. Always set to `message`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"message"` - The tool invocation context(s). + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - - `"direct"` + An output message from the model. - - `"programmatic"` + - `id: string` - - `defer_loading: optional boolean` + The unique ID of the output message. - Whether this function should be deferred and discovered via tool search. + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - - `description: optional string` + The content of the output message. - - `output_schema: optional map[unknown]` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + A text output from the model. - - `parameters: optional unknown` + - `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 }` - - `strict: optional boolean` + The annotations of the text output. - 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. + - `FileCitation object { file_id, filename, index, type }` - - `Custom object { name, type, allowed_callers, 3 more }` + A citation to a file. - 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 file cited. - The type of the custom tool. Always `custom`. + - `index: number` - - `"custom"` + The index of the file in the list of files. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "file_citation"` - The tool invocation context(s). + The type of the file citation. Always `file_citation`. - - `"direct"` + - `"file_citation"` - - `"programmatic"` + - `URLCitation object { end_index, start_index, title, 2 more }` - - `defer_loading: optional boolean` + A citation for a web resource used to generate a model response. - Whether this tool should be deferred and discovered via tool search. + - `end_index: number` - - `description: optional string` + The index of the last character of the URL citation in the message. - Optional description of the custom tool, used to provide more context. + - `start_index: number` - - `format: optional object { type } or object { definition, syntax, type }` + The index of the first character of the URL citation in the message. - The input format for the custom tool. Default is unconstrained text. + - `title: string` - - `Text object { type }` + The title of the web resource. - Unconstrained free-form text. + - `type: "url_citation"` - - `type: "text"` + The type of the URL citation. Always `url_citation`. - Unconstrained text format. Always `text`. + - `"url_citation"` - - `"text"` + - `url: string` - - `Grammar object { definition, syntax, type }` + The URL of the web resource. - A grammar defined by the user. + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - - `definition: string` + A citation for a container file used to generate a model response. - The grammar definition. + - `container_id: string` - - `syntax: "lark" or "regex"` + The ID of the container file. - The syntax of the grammar definition. One of `lark` or `regex`. + - `end_index: number` - - `"lark"` + The index of the last character of the container file citation in the message. - - `"regex"` + - `file_id: string` - - `type: "grammar"` + The ID of the file. - Grammar format. Always `grammar`. + - `filename: string` - - `"grammar"` + The filename of the container file cited. - - `type: "namespace"` + - `start_index: number` - The type of the tool. Always `namespace`. + The index of the first character of the container file citation in the message. - - `"namespace"` + - `type: "container_file_citation"` - - `ToolSearch object { type, description, execution, parameters }` + The type of the container file citation. Always `container_file_citation`. - Hosted or BYOT tool search configuration for deferred tools. + - `"container_file_citation"` - - `type: "tool_search"` + - `FilePath object { file_id, index, type }` - The type of the tool. Always `tool_search`. + A path to a file. - - `"tool_search"` + - `file_id: string` - - `description: optional string` + The ID of the file. - Description shown to the model for a client-executed tool search tool. + - `index: number` - - `execution: optional "server" or "client"` + The index of the file in the list of files. - Whether tool search is executed by the server or by the client. + - `type: "file_path"` - - `"server"` + The type of the file path. Always `file_path`. - - `"client"` + - `"file_path"` - - `parameters: optional unknown` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - Parameter schema for a client-executed tool search tool. + - `token: string` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `bytes: array of 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). + - `logprob: number` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `top_logprobs: array of object { token, bytes, logprob }` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `token: string` - - `"web_search_preview"` + - `bytes: array of number` - - `"web_search_preview_2025_03_11"` + - `logprob: number` - - `search_content_types: optional array of "text" or "image"` + - `text: string` - - `"text"` + The text output from the model. - - `"image"` + - `type: "output_text"` - - `search_context_size: optional "low" or "medium" or "high"` + The type of the output text. Always `output_text`. - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + - `"output_text"` - - `"low"` + - `BetaResponseOutputRefusal object { refusal, type }` - - `"medium"` + A refusal from the model. - - `"high"` + - `refusal: string` - - `user_location: optional object { type, city, country, 2 more }` + The refusal explanation from the model. - The user's location. + - `type: "refusal"` - - `type: "approximate"` + The type of the refusal. Always `refusal`. - The type of location approximation. Always `approximate`. + - `"refusal"` - - `"approximate"` + - `role: "assistant"` - - `city: optional string` + The role of the output message. Always `assistant`. - Free text input for the city of the user, e.g. `San Francisco`. + - `"assistant"` - - `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 message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `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: "message"` - - `ApplyPatch object { type, allowed_callers }` + The type of the output message. Always `message`. - Allows the assistant to create, delete, or update files using unified diffs. + - `"message"` - - `type: "apply_patch"` + - `agent: optional object { agent_name }` - The type of the tool. Always `apply_patch`. + The agent that produced this item. - - `"apply_patch"` + - `agent_name: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The canonical name of the agent that produced this item. - 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"` - - `type: "tool_search_output"` + - `"final_answer"` - The item type. Always `tool_search_output`. + - `FileSearchCall object { id, queries, status, 3 more }` - - `"tool_search_output"` + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - - `id: optional string` + - `id: string` - The unique ID of this tool search output. + The unique ID of the file search tool call. - - `agent: optional object { agent_name }` + - `queries: array of string` - The agent that produced this item. + The queries used to search for files. - - `agent_name: string` + - `status: "in_progress" or "searching" or "completed" or 2 more` - The canonical name of the agent that produced this item. + 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 output. + - `"file_search_call"` - - `"in_progress"` + - `agent: optional object { agent_name }` - - `"completed"` + The agent that produced this item. - - `"incomplete"` + - `agent_name: string` - - `AdditionalTools object { role, tools, type, 2 more }` + The canonical name of the agent that produced this item. - - `role: "developer"` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - The role that provided the additional tools. Only `developer` is supported. + The results of the file search tool call. - - `"developer"` + - `attributes: optional map[string or number or boolean]` - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 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. - A list of additional tools made available at this item. + - `string` - - `Function object { name, parameters, strict, 5 more }` + - `number` - 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). + - `boolean` - - `name: string` + - `file_id: optional string` - The name of the function to call. + The unique ID of the file. - - `parameters: map[unknown]` + - `filename: optional string` - A JSON schema object describing the parameters of the function. + The name of the file. - - `strict: boolean` + - `score: optional number` - Whether strict parameter validation is enforced for this function tool. + The relevance score of the file - a value between 0 and 1. - - `type: "function"` + - `text: optional string` - The type of the function tool. Always `function`. + The text that was retrieved from the file. - - `"function"` + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - The tool invocation context(s). + - `id: string` - - `"direct"` + The unique ID of the computer call. - - `"programmatic"` + - `call_id: string` - - `defer_loading: optional boolean` + An identifier used when responding to the tool call with output. - Whether this function is deferred and loaded via tool search. + - `pending_safety_checks: array of object { id, code, message }` - - `description: optional string` + The pending safety checks for the computer call. - A description of the function. Used by the model to determine whether or not to call the function. + - `id: string` - - `output_schema: optional map[unknown]` + The ID of the pending safety check. - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `code: optional string` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + The type of the pending safety check. - 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). + - `message: optional string` - - `type: "file_search"` + Details about the pending safety check. - The type of the file search tool. Always `file_search`. + - `status: "in_progress" or "completed" or "incomplete"` - - `"file_search"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `vector_store_ids: array of string` + - `"in_progress"` - The IDs of the vector stores to search. + - `"completed"` - - `filters: optional object { key, type, value } or object { filters, type }` + - `"incomplete"` - A filter to apply. + - `type: "computer_call"` - - `ComparisonFilter object { key, type, value }` + The type of the computer call. Always `computer_call`. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"computer_call"` - - `key: string` + - `action: optional BetaComputerAction` - The key to compare against the value. + A click action. - - `type: "eq" or "ne" or "gt" or 5 more` + - `Click object { button, type, x, 2 more }` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + A click action. - - `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 + - `button: "left" or "right" or "wheel" or 2 more` - - `"eq"` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `"ne"` + - `"left"` - - `"gt"` + - `"right"` - - `"gte"` + - `"wheel"` - - `"lt"` + - `"back"` - - `"lte"` + - `"forward"` - - `"in"` + - `type: "click"` - - `"nin"` + Specifies the event type. For a click action, this property is always `click`. - - `value: string or number or boolean or array of string or number` + - `"click"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `x: number` - - `string` + The x-coordinate where the click occurred. - - `number` + - `y: number` - - `boolean` + The y-coordinate where the click occurred. - - `array of string or number` + - `keys: optional array of string` - - `string` + The keys being held while clicking. - - `number` + - `DoubleClick object { keys, type, x, y }` - - `CompoundFilter object { filters, type }` + A double click action. - Combine multiple filters using `and` or `or`. + - `keys: array of string` - - `filters: array of object { key, type, value } or unknown` + The keys being held while double-clicking. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `type: "double_click"` - - `ComparisonFilter object { key, type, value }` + Specifies the event type. For a double click action, this property is always set to `double_click`. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"double_click"` - - `key: string` + - `x: number` - The key to compare against the value. + The x-coordinate where the double click occurred. - - `type: "eq" or "ne" or "gt" or 5 more` + - `y: number` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The y-coordinate where the double click occurred. - - `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 + - `Drag object { path, type, keys }` - - `"eq"` + A drag action. - - `"ne"` + - `path: array of object { x, y }` - - `"gt"` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `"gte"` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `"lt"` + - `x: number` - - `"lte"` + The x-coordinate. - - `"in"` + - `y: number` - - `"nin"` + The y-coordinate. - - `value: string or number or boolean or array of string or number` + - `type: "drag"` - The value to compare against the attribute key; supports string, number, or boolean types. + Specifies the event type. For a drag action, this property is always set to `drag`. - - `string` + - `"drag"` - - `number` + - `keys: optional array of string` - - `boolean` + The keys being held while dragging the mouse. - - `array of string or number` + - `Keypress object { keys, type }` - - `string` + A collection of keypresses the model would like to perform. - - `number` + - `keys: array of string` - - `unknown` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `type: "and" or "or"` + - `type: "keypress"` - Type of operation: `and` or `or`. + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `"and"` + - `"keypress"` - - `"or"` + - `Move object { type, x, y, keys }` - - `max_num_results: optional number` + A mouse move action. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `type: "move"` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + Specifies the event type. For a move action, this property is always set to `move`. - Ranking options for search. + - `"move"` - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `x: number` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + The x-coordinate to move to. - - `embedding_weight: number` + - `y: number` - The weight of the embedding in the reciprocal ranking fusion. + The y-coordinate to move to. - - `text_weight: number` + - `keys: optional array of string` - The weight of the text in the reciprocal ranking fusion. + The keys being held while moving the mouse. - - `ranker: optional "auto" or "default-2024-11-15"` + - `Screenshot object { type }` - The ranker to use for the file search. + A screenshot action. - - `"auto"` + - `type: "screenshot"` - - `"default-2024-11-15"` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `score_threshold: optional number` + - `"screenshot"` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `Computer object { type }` + A scroll action. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `scroll_x: number` - - `type: "computer"` + The horizontal scroll distance. - The type of the computer tool. Always `computer`. + - `scroll_y: number` - - `"computer"` + The vertical scroll distance. - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `type: "scroll"` - 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 scroll action, this property is always set to `scroll`. - - `display_height: number` + - `"scroll"` - The height of the computer display. + - `x: number` - - `display_width: number` + The x-coordinate where the scroll occurred. - The width of the computer display. + - `y: number` - - `environment: "windows" or "mac" or "linux" or 2 more` + The y-coordinate where the scroll occurred. - The type of computer environment to control. + - `keys: optional array of string` - - `"windows"` + The keys being held while scrolling. - - `"mac"` + - `Type object { text, type }` - - `"linux"` + An action to type in text. - - `"ubuntu"` + - `text: string` - - `"browser"` + The text to type. - - `type: "computer_use_preview"` + - `type: "type"` - The type of the computer use tool. Always `computer_use_preview`. + Specifies the event type. For a type action, this property is always set to `type`. - - `"computer_use_preview"` + - `"type"` - - `WebSearch object { type, filters, search_context_size, user_location }` + - `Wait object { type }` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + A wait action. - - `type: "web_search" or "web_search_2025_08_26"` + - `type: "wait"` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + Specifies the event type. For a wait action, this property is always set to `wait`. - - `"web_search"` + - `"wait"` - - `"web_search_2025_08_26"` + - `actions: optional BetaComputerActionList` - - `filters: optional object { allowed_domains }` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - Filters for the search. + - `Click object { button, type, x, 2 more }` - - `allowed_domains: optional array of string` + A click action. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `DoubleClick object { keys, type, x, y }` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + A double click action. - - `search_context_size: optional "low" or "medium" or "high"` + - `Drag object { path, type, keys }` - 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 drag action. - - `"low"` + - `Keypress object { keys, type }` - - `"medium"` + A collection of keypresses the model would like to perform. - - `"high"` + - `Move object { type, x, y, keys }` - - `user_location: optional object { city, country, region, 2 more }` + A mouse move action. - The approximate location of the user. + - `Screenshot object { type }` - - `city: optional string` + A screenshot action. - Free text input for the city of the user, e.g. `San Francisco`. + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `country: optional string` + A scroll action. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `Type object { text, type }` - - `region: optional string` + An action to type in text. - Free text input for the region of the user, e.g. `California`. + - `Wait object { type }` - - `timezone: optional string` + A wait action. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `agent: optional object { agent_name }` - - `type: optional "approximate"` + The agent that produced this item. - The type of location approximation. Always `approximate`. + - `agent_name: string` - - `"approximate"` + The canonical name of the agent that produced this item. - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `ComputerCallOutput object { call_id, output, type, 4 more }` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + The output of a computer tool call. - - `server_label: string` + - `call_id: string` - A label for this MCP server, used to identify it in tool calls. + The ID of the computer tool call that produced the output. - - `type: "mcp"` + - `output: BetaResponseComputerToolCallOutputScreenshot` - The type of the MCP tool. Always `mcp`. + A computer screenshot image used with the computer use tool. - - `"mcp"` + - `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. - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `image_url: optional string` - List of allowed tool names or a filter object. + The URL of the screenshot image. - - `McpAllowedTools = array of string` + - `type: "computer_call_output"` - A string array of allowed tool names + The type of the computer tool call output. Always `computer_call_output`. - - `McpToolFilter object { read_only, tool_names }` + - `"computer_call_output"` - A filter object to specify which tools are allowed. + - `id: optional string` - - `read_only: optional boolean` + The ID of the computer 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. + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `tool_names: optional array of string` + The safety checks reported by the API that have been acknowledged by the developer. - List of allowed tool names. + - `id: string` - - `authorization: optional string` + The ID of the pending safety check. - 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. + - `code: optional string` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + The type of the pending safety check. - 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). + - `message: optional string` - Currently supported `connector_id` values are: + Details about the pending safety check. - - 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` + - `agent: optional object { agent_name }` - - `"connector_dropbox"` + The agent that produced this item. - - `"connector_gmail"` + - `agent_name: string` - - `"connector_googlecalendar"` + The canonical name of the agent that produced this item. - - `"connector_googledrive"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"connector_microsoftteams"` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - `"connector_outlookcalendar"` + - `"in_progress"` - - `"connector_outlookemail"` + - `"completed"` - - `"connector_sharepoint"` + - `"incomplete"` - - `defer_loading: optional boolean` + - `WebSearchCall object { id, action, status, 2 more }` - Whether this MCP tool is deferred and discovered via tool search. + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `headers: optional map[string]` + - `id: string` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The unique ID of the web search tool call. - - `require_approval: optional object { always, never } or "always" or "never"` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - Specify which of the MCP server's tools require approval. + 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). - - `McpToolApprovalFilter object { always, never }` + - `Search object { type, queries, query, sources }` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + Action type "search" - Performs a web search query. - - `always: optional object { read_only, tool_names }` + - `type: "search"` - A filter object to specify which tools are allowed. + The action type. - - `read_only: optional boolean` + - `"search"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `queries: optional array of string` - - `tool_names: optional array of string` + The search queries. - List of allowed tool names. + - `query: optional string` - - `never: optional object { read_only, tool_names }` + The search query. - A filter object to specify which tools are allowed. + - `sources: optional array of object { type, url }` - - `read_only: optional boolean` + The sources used in the search. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `type: "url"` - - `tool_names: optional array of string` + The type of source. Always `url`. - List of allowed tool names. + - `"url"` - - `McpToolApprovalSetting = "always" or "never"` + - `url: 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. + The URL of the source. - - `"always"` + - `OpenPage object { type, url }` - - `"never"` + Action type "open_page" - Opens a specific URL from search results. - - `server_description: optional string` + - `type: "open_page"` - Optional description of the MCP server, used to provide more context. + The action type. - - `server_url: optional string` + - `"open_page"` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `url: optional string` - - `tunnel_id: optional string` + The URL opened by 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. + - `FindInPage object { pattern, type, url }` - - `CodeInterpreter object { container, type, allowed_callers }` + Action type "find_in_page": Searches for a pattern within a loaded page. - A tool that runs Python code to help generate a response to a prompt. + - `pattern: string` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + The pattern or text to search for within the page. - 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: "find_in_page"` - - `string` + The action type. - The container ID. + - `"find_in_page"` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `url: string` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + The URL of the page searched for the pattern. - - `type: "auto"` + - `status: "in_progress" or "searching" or "completed" or "failed"` - Always `auto`. + The status of the web search tool call. - - `"auto"` + - `"in_progress"` - - `file_ids: optional array of string` + - `"searching"` - An optional list of uploaded files to make available to your code. + - `"completed"` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `"failed"` - The memory limit for the code interpreter container. + - `type: "web_search_call"` - - `"1g"` + The type of the web search tool call. Always `web_search_call`. - - `"4g"` + - `"web_search_call"` - - `"16g"` + - `agent: optional object { agent_name }` - - `"64g"` + The agent that produced this item. - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `agent_name: string` - Network access policy for the container. + The canonical name of the agent that produced this item. - - `BetaContainerNetworkPolicyDisabled object { type }` + - `FunctionCall object { arguments, call_id, name, 6 more }` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `type: "code_interpreter"` + - `arguments: string` - The type of the code interpreter tool. Always `code_interpreter`. + A JSON string of the arguments to pass to the function. - - `"code_interpreter"` + - `call_id: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The unique ID of the function tool call generated by the model. - The tool invocation context(s). + - `name: string` - - `"direct"` + The name of the function to run. - - `"programmatic"` + - `type: "function_call"` - - `ProgrammaticToolCalling object { type }` + The type of the function tool call. Always `function_call`. - - `type: "programmatic_tool_calling"` + - `"function_call"` - The type of the tool. Always `programmatic_tool_calling`. + - `id: optional string` - - `"programmatic_tool_calling"` + The unique ID of the function tool call. - - `ImageGeneration object { type, action, background, 9 more }` + - `agent: optional object { agent_name }` - A tool that generates images using the GPT image models. + The agent that produced this item. - - `type: "image_generation"` + - `agent_name: string` - The type of the image generation tool. Always `image_generation`. + The canonical name of the agent that produced this item. - - `"image_generation"` + - `caller: optional object { type } or object { caller_id, type }` - - `action: optional "generate" or "edit" or "auto"` + The execution context that produced this tool call. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `Direct object { type }` - - `"generate"` + - `type: "direct"` - - `"edit"` + - `"direct"` - - `"auto"` + - `Program object { caller_id, type }` - - `background: optional "transparent" or "opaque" or "auto"` + - `caller_id: string` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + The call ID of the program item that produced this tool call. - - `"transparent"` + - `type: "program"` - - `"opaque"` + - `"program"` - - `"auto"` + - `namespace: optional string` - - `input_fidelity: optional "high" or "low"` + The namespace of the function to run. - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"high"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"low"` + - `"in_progress"` - - `input_image_mask: optional object { file_id, image_url }` + - `"completed"` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `"incomplete"` - - `file_id: optional string` + - `FunctionCallOutput object { call_id, output, type, 4 more }` - File ID for the mask image. + The output of a function tool call. - - `image_url: optional string` + - `call_id: string` - Base64-encoded mask image. + The unique ID of the function tool call generated by the model. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - The image generation model to use. Default: `gpt-image-1`. + Text, image, or file output of the function tool call. - `string` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + A JSON string of the output of the function tool call. - The image generation model to use. Default: `gpt-image-1`. + - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - - `"gpt-image-1"` + An array of content outputs (text, image, file) for the function tool call. - - `"gpt-image-1-mini"` + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - - `"gpt-image-1.5"` + A text input to the model. - - `moderation: optional "auto" or "low"` + - `text: string` - Moderation level for the generated image. Default: `auto`. + The text input to the model. - - `"auto"` + - `type: "input_text"` - - `"low"` + The type of the input item. Always `input_text`. - - `output_compression: optional number` + - `"input_text"` - Compression level for the output image. Default: 100. + - `prompt_cache_breakpoint: optional object { mode }` - - `output_format: optional "png" or "webp" or "jpeg"` + 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 format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `mode: "explicit"` - - `"png"` + The breakpoint mode. Always `explicit`. - - `"webp"` + - `"explicit"` - - `"jpeg"` + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - - `partial_images: optional number` + An image input to the model. Learn about [image inputs](/docs/guides/vision) - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `type: "input_image"` - - `quality: optional "low" or "medium" or "high" or "auto"` + The type of the input item. Always `input_image`. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `"input_image"` - - `"low"` + - `detail: optional "low" or "high" or "auto" or "original"` - - `"medium"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + + - `"low"` - `"high"` - `"auto"` - - `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`. + - `"original"` - - `"1024x1024"` + - `file_id: optional string` - - `"1024x1536"` + The ID of the file to be sent to the model. - - `"1536x1024"` + - `image_url: optional string` - - `"auto"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `LocalShell object { type }` + - `prompt_cache_breakpoint: optional object { mode }` - A tool that allows the model to execute shell commands in a local environment. + 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: "local_shell"` + - `mode: "explicit"` - The type of the local shell tool. Always `local_shell`. + The breakpoint mode. Always `explicit`. - - `"local_shell"` + - `"explicit"` - - `Shell object { type, allowed_callers, environment }` + - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` - A tool that allows the model to execute shell commands. + A file input to the model. - - `type: "shell"` + - `type: "input_file"` - The type of the shell tool. Always `shell`. + The type of the input item. Always `input_file`. - - `"shell"` + - `"input_file"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `detail: optional "auto" or "low" or "high"` - The tool invocation context(s). + 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"` - - `"programmatic"` + - `"low"` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `"high"` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `file_data: optional string` - - `BetaLocalEnvironment object { type, skills }` + The base64-encoded data of the file to be sent to the model. - - `BetaContainerReference object { container_id, type }` + - `file_id: optional string` - - `Custom object { name, type, allowed_callers, 3 more }` + The ID of the file to be sent to the model. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `file_url: optional string` - - `name: string` + The URL of the file to be sent to the model. - The name of the custom tool, used to identify it in tool calls. + - `filename: optional string` - - `type: "custom"` + The name of the file to be sent to the model. - The type of the custom tool. Always `custom`. + - `prompt_cache_breakpoint: optional object { mode }` - - `"custom"` + 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. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `mode: "explicit"` - The tool invocation context(s). + The breakpoint mode. Always `explicit`. - - `"direct"` + - `"explicit"` - - `"programmatic"` + - `type: "function_call_output"` - - `defer_loading: optional boolean` + The type of the function tool call output. Always `function_call_output`. - Whether this tool should be deferred and discovered via tool search. + - `"function_call_output"` - - `description: optional string` + - `id: optional string` - Optional description of the custom tool, used to provide more context. + The unique ID of the function tool call output. Populated when this item is returned via API. - - `format: optional object { type } or object { definition, syntax, type }` + - `agent: optional object { agent_name }` - The input format for the custom tool. Default is unconstrained text. + The agent that produced this item. - - `Text object { type }` + - `agent_name: string` - Unconstrained free-form text. + The canonical name of the agent that produced this item. - - `type: "text"` + - `caller: optional object { type } or object { caller_id, type }` - Unconstrained text format. Always `text`. + The execution context that produced this tool call. - - `"text"` + - `Direct object { type }` - - `Grammar object { definition, syntax, type }` + - `type: "direct"` - A grammar defined by the user. + The caller type. Always `direct`. - - `definition: string` + - `"direct"` - The grammar definition. + - `Program object { caller_id, type }` - - `syntax: "lark" or "regex"` + - `caller_id: string` - The syntax of the grammar definition. One of `lark` or `regex`. + The call ID of the program item that produced this tool call. - - `"lark"` + - `type: "program"` - - `"regex"` + The caller type. Always `program`. - - `type: "grammar"` + - `"program"` - Grammar format. Always `grammar`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"grammar"` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `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. + - `AgentMessage object { author, content, recipient, 3 more }` - - `name: string` + A message routed between agents. - The namespace name used in tool calls (for example, `crm`). + - `author: string` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + The sending agent identity. - The function/custom tools available inside this namespace. + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - - `Function object { name, type, allowed_callers, 5 more }` + Plaintext, image, or encrypted content sent between agents. - - `name: string` + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - - `type: "function"` + A text input to the model. - - `"function"` + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + An image input to the model. Learn about [image inputs](/docs/guides/vision) - The tool invocation context(s). + - `EncryptedContent object { encrypted_content, type }` - - `"direct"` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `"programmatic"` + - `encrypted_content: string` - - `defer_loading: optional boolean` + Opaque encrypted content. - Whether this function should be deferred and discovered via tool search. + - `type: "encrypted_content"` - - `description: optional string` + The type of the input item. Always `encrypted_content`. - - `output_schema: optional map[unknown]` + - `"encrypted_content"` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `recipient: string` - - `parameters: optional unknown` + The destination agent identity. - - `strict: optional boolean` + - `type: "agent_message"` - 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 item type. Always `agent_message`. - - `Custom object { name, type, allowed_callers, 3 more }` + - `"agent_message"` - 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 this agent message item. - The name of the custom tool, used to identify it in tool calls. + - `agent: optional object { agent_name }` - - `type: "custom"` + The agent that produced this item. - The type of the custom tool. Always `custom`. + - `agent_name: string` - - `"custom"` + The canonical name of the agent that produced this item. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `MultiAgentCall object { action, arguments, call_id, 3 more }` - The tool invocation context(s). + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `"direct"` + The multi-agent action that was executed. - - `"programmatic"` + - `"spawn_agent"` - - `defer_loading: optional boolean` + - `"interrupt_agent"` - Whether this tool should be deferred and discovered via tool search. + - `"list_agents"` - - `description: optional string` + - `"send_message"` - Optional description of the custom tool, used to provide more context. + - `"followup_task"` - - `format: optional object { type } or object { definition, syntax, type }` + - `"wait_agent"` - The input format for the custom tool. Default is unconstrained text. + - `arguments: string` - - `Text object { type }` + The action arguments as a JSON string. - Unconstrained free-form text. + - `call_id: string` - - `type: "text"` + The unique ID linking this call to its output. - Unconstrained text format. Always `text`. + - `type: "multi_agent_call"` - - `"text"` + The item type. Always `multi_agent_call`. - - `Grammar object { definition, syntax, type }` + - `"multi_agent_call"` - A grammar defined by the user. + - `id: optional string` - - `definition: string` + The unique ID of this multi-agent call. - The grammar definition. + - `agent: optional object { agent_name }` - - `syntax: "lark" or "regex"` + The agent that produced this item. - The syntax of the grammar definition. One of `lark` or `regex`. + - `agent_name: string` - - `"lark"` + The canonical name of the agent that produced this item. - - `"regex"` + - `MultiAgentCallOutput object { action, call_id, output, 3 more }` - - `type: "grammar"` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - Grammar format. Always `grammar`. + The multi-agent action that produced this result. - - `"grammar"` + - `"spawn_agent"` - - `type: "namespace"` + - `"interrupt_agent"` - The type of the tool. Always `namespace`. + - `"list_agents"` - - `"namespace"` + - `"send_message"` - - `ToolSearch object { type, description, execution, parameters }` + - `"followup_task"` - Hosted or BYOT tool search configuration for deferred tools. + - `"wait_agent"` - - `type: "tool_search"` + - `call_id: string` - The type of the tool. Always `tool_search`. + The unique ID of the multi-agent call. - - `"tool_search"` + - `output: array of object { text, type, annotations }` - - `description: optional string` + Text output returned by the multi-agent action. - Description shown to the model for a client-executed tool search tool. + - `text: string` - - `execution: optional "server" or "client"` + The text content. - Whether tool search is executed by the server or by the client. + - `type: "output_text"` - - `"server"` + The content type. Always `output_text`. - - `"client"` + - `"output_text"` - - `parameters: optional unknown` + - `annotations: optional 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 }` - Parameter schema for a client-executed tool search tool. + Citations associated with the text content. - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `FileCitation object { file_id, filename, index, 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). + - `file_id: string` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + The ID of the file. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `filename: string` - - `"web_search_preview"` + The filename of the file cited. - - `"web_search_preview_2025_03_11"` + - `index: number` - - `search_content_types: optional array of "text" or "image"` + The index of the file in the list of files. - - `"text"` + - `type: "file_citation"` - - `"image"` + The citation type. Always `file_citation`. - - `search_context_size: optional "low" or "medium" or "high"` + - `"file_citation"` - 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. + - `URLCitation object { end_index, start_index, title, 2 more }` - - `"low"` + - `end_index: number` - - `"medium"` + The index of the last character of the citation in the message. - - `"high"` + - `start_index: number` - - `user_location: optional object { type, city, country, 2 more }` + The index of the first character of the citation in the message. - The user's location. + - `title: string` - - `type: "approximate"` + The title of the cited resource. - The type of location approximation. Always `approximate`. + - `type: "url_citation"` - - `"approximate"` + The citation type. Always `url_citation`. - - `city: optional string` + - `"url_citation"` - Free text input for the city of the user, e.g. `San Francisco`. + - `url: string` - - `country: optional string` + The URL of the cited resource. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - - `region: optional string` + - `container_id: string` - Free text input for the region of the user, e.g. `California`. + The ID of the container. - - `timezone: optional string` + - `end_index: number` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The index of the last character of the citation in the message. - - `ApplyPatch object { type, allowed_callers }` + - `file_id: string` - Allows the assistant to create, delete, or update files using unified diffs. + The ID of the container file. - - `type: "apply_patch"` + - `filename: string` - The type of the tool. Always `apply_patch`. + The filename of the container file cited. - - `"apply_patch"` + - `start_index: number` - - `allowed_callers: optional array of "direct" or "programmatic"` + The index of the first character of the citation in the message. - The tool invocation context(s). + - `type: "container_file_citation"` - - `"direct"` + The citation type. Always `container_file_citation`. - - `"programmatic"` + - `"container_file_citation"` - - `type: "additional_tools"` + - `type: "multi_agent_call_output"` - The item type. Always `additional_tools`. + The item type. Always `multi_agent_call_output`. - - `"additional_tools"` + - `"multi_agent_call_output"` - `id: optional string` - The unique ID of this additional tools item. + The unique ID of this multi-agent call output. - `agent: optional object { agent_name }` @@ -181026,36 +181318,21 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `Reasoning object { id, summary, type, 4 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 object { text, type }` - - Reasoning summary content. - - - `text: string` + - `ToolSearchCall object { arguments, type, id, 4 more }` - A summary of the reasoning output from the model so far. + - `arguments: unknown` - - `type: "summary_text"` + The arguments supplied to the tool search call. - The type of the object. Always `summary_text`. + - `type: "tool_search_call"` - - `"summary_text"` + The item type. Always `tool_search_call`. - - `type: "reasoning"` + - `"tool_search_call"` - The type of the object. Always `reasoning`. + - `id: optional string` - - `"reasoning"` + The unique ID of this tool search call. - `agent: optional object { agent_name }` @@ -181065,30 +181342,21 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `content: optional array of object { text, type }` - - Reasoning text content. - - - `text: string` - - The reasoning text from the model. + - `call_id: optional string` - - `type: "reasoning_text"` + The unique ID of the tool search call generated by the model. - The type of the reasoning text. Always `reasoning_text`. + - `execution: optional "server" or "client"` - - `"reasoning_text"` + Whether tool search was executed by the server or by the client. - - `encrypted_content: optional string` + - `"server"` - 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. + - `"client"` - `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 tool search call. - `"in_progress"` @@ -181096,2311 +181364,2335 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `Compaction object { encrypted_content, type, id, agent }` - - 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. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `ImageGenerationCall object { id, result, status, 2 more }` + - `ToolSearchOutput object { tools, type, id, 4 more }` - An image generation request made by 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` - - `id: string` + The loaded tool definitions returned by the tool search output. - The unique ID of the image generation call. + - `Function object { name, parameters, strict, 5 more }` - - `result: 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 generated image encoded in base64. + - `name: string` - - `status: "in_progress" or "completed" or "generating" or "failed"` + The name of the function to call. - The status of the image generation call. + - `parameters: map[unknown]` - - `"in_progress"` + A JSON schema object describing the parameters of the function. - - `"completed"` + - `strict: boolean` - - `"generating"` + Whether strict parameter validation is enforced for this function tool. - - `"failed"` + - `type: "function"` - - `type: "image_generation_call"` + The type of the function tool. Always `function`. - The type of the image generation call. Always `image_generation_call`. + - `"function"` - - `"image_generation_call"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `agent: optional object { agent_name }` + The tool invocation context(s). - The agent that produced this item. + - `"direct"` - - `agent_name: string` + - `"programmatic"` - The canonical name of the agent that produced this item. + - `defer_loading: optional boolean` - - `CodeInterpreterCall object { id, code, container_id, 4 more }` + Whether this function is deferred and loaded via tool search. - A tool call to run code. + - `description: optional string` - - `id: string` + A description of the function. Used by the model to determine whether or not to call the function. - The unique ID of the code interpreter tool call. + - `output_schema: optional map[unknown]` - - `code: string` + A JSON schema object describing the JSON value encoded in string outputs for this function. - The code to run, or null if not available. + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `container_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 ID of the container used to run the code. + - `type: "file_search"` - - `outputs: array of object { logs, type } or object { type, url }` + The type of the file search tool. Always `file_search`. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `"file_search"` - - `Logs object { logs, type }` + - `vector_store_ids: array of string` - The logs output from the code interpreter. + The IDs of the vector stores to search. - - `logs: string` + - `filters: optional object { key, type, value } or object { filters, type }` - The logs output from the code interpreter. + A filter to apply. - - `type: "logs"` + - `ComparisonFilter object { key, type, value }` - The type of the output. Always `logs`. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"logs"` + - `key: string` - - `Image object { type, url }` + The key to compare against the value. - The image output from the code interpreter. + - `type: "eq" or "ne" or "gt" or 5 more` - - `type: "image"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The type of the output. Always `image`. + - `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 - - `"image"` + - `"eq"` - - `url: string` + - `"ne"` - The URL of the image output from the code interpreter. + - `"gt"` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `"gte"` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `"lt"` - - `"in_progress"` + - `"lte"` - - `"completed"` + - `"in"` - - `"incomplete"` + - `"nin"` - - `"interpreting"` + - `value: string or number or boolean or array of string or number` - - `"failed"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `type: "code_interpreter_call"` + - `string` - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `number` - - `"code_interpreter_call"` + - `boolean` - - `agent: optional object { agent_name }` + - `array of string or number` - The agent that produced this item. + - `string` - - `agent_name: string` + - `number` - The canonical name of the agent that produced this item. + - `CompoundFilter object { filters, type }` - - `LocalShellCall object { id, action, call_id, 3 more }` + Combine multiple filters using `and` or `or`. - A tool call to run a command on the local shell. + - `filters: array of object { key, type, value } or unknown` - - `id: string` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The unique ID of the local shell call. + - `ComparisonFilter object { key, type, value }` - - `action: object { command, env, type, 3 more }` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - Execute a shell command on the server. + - `key: string` - - `command: array of string` + The key to compare against the value. - The command to run. + - `type: "eq" or "ne" or "gt" or 5 more` - - `env: map[string]` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - Environment variables to set for the command. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `type: "exec"` + - `"eq"` - The type of the local shell action. Always `exec`. + - `"ne"` - - `"exec"` + - `"gt"` - - `timeout_ms: optional number` + - `"gte"` - Optional timeout in milliseconds for the command. + - `"lt"` - - `user: optional string` + - `"lte"` - Optional user to run the command as. + - `"in"` - - `working_directory: optional string` + - `"nin"` - Optional working directory to run the command in. + - `value: string or number or boolean or array of string or number` - - `call_id: string` + The value to compare against the attribute key; supports string, number, or boolean types. - The unique ID of the local shell tool call generated by the model. + - `string` - - `status: "in_progress" or "completed" or "incomplete"` + - `number` - The status of the local shell call. + - `boolean` - - `"in_progress"` + - `array of string or number` - - `"completed"` + - `string` - - `"incomplete"` + - `number` - - `type: "local_shell_call"` + - `unknown` - The type of the local shell call. Always `local_shell_call`. + - `type: "and" or "or"` - - `"local_shell_call"` + Type of operation: `and` or `or`. - - `agent: optional object { agent_name }` + - `"and"` - The agent that produced this item. + - `"or"` - - `agent_name: string` + - `max_num_results: optional number` - The canonical name of the agent that produced this item. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `LocalShellCallOutput object { id, output, type, 2 more }` + - `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"` - - `agent: optional object { agent_name }` + The ranker to use for the file search. - The agent that produced this item. + - `"auto"` - - `agent_name: string` + - `"default-2024-11-15"` - The canonical name of the agent that produced this item. + - `score_threshold: optional number` - - `status: optional "in_progress" or "completed" or "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. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + - `Computer object { type }` - - `"in_progress"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"completed"` + - `type: "computer"` - - `"incomplete"` + The type of the computer tool. Always `computer`. - - `ShellCall object { action, call_id, type, 5 more }` + - `"computer"` - A tool representing a request to execute one or more shell commands. + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `action: object { commands, max_output_length, timeout_ms }` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The shell commands and limits that describe how to run the tool call. + - `display_height: number` - - `commands: array of string` + The height of the computer display. - Ordered shell commands for the execution environment to run. + - `display_width: number` - - `max_output_length: optional number` + The width of the computer display. - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `environment: "windows" or "mac" or "linux" or 2 more` - - `timeout_ms: optional number` + The type of computer environment to control. - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `"windows"` - - `call_id: string` + - `"mac"` - The unique ID of the shell tool call generated by the model. + - `"linux"` - - `type: "shell_call"` + - `"ubuntu"` - The type of the item. Always `shell_call`. + - `"browser"` - - `"shell_call"` + - `type: "computer_use_preview"` - - `id: optional string` + The type of the computer use tool. Always `computer_use_preview`. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `"computer_use_preview"` - - `agent: optional object { agent_name }` + - `WebSearch object { type, filters, search_context_size, user_location }` - The agent that produced this item. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `agent_name: string` + - `type: "web_search" or "web_search_2025_08_26"` - The canonical name of the agent that produced this item. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `caller: optional object { type } or object { caller_id, type }` + - `"web_search"` - The execution context that produced this tool call. + - `"web_search_2025_08_26"` - - `Direct object { type }` + - `filters: optional object { allowed_domains }` - - `type: "direct"` + Filters for the search. - The caller type. Always `direct`. + - `allowed_domains: optional array of string` - - `"direct"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `Program object { caller_id, type }` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `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"` - The caller type. Always `program`. + - `"medium"` - - `"program"` + - `"high"` - - `environment: optional BetaLocalEnvironment or BetaContainerReference` + - `user_location: optional object { city, country, region, 2 more }` - The environment to execute the shell commands in. + The approximate location of the user. - - `BetaLocalEnvironment object { type, skills }` + - `city: optional string` - - `BetaContainerReference object { container_id, type }` + Free text input for the city of the user, e.g. `San Francisco`. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `country: optional string` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"in_progress"` + - `region: optional string` - - `"completed"` + Free text input for the region of the user, e.g. `California`. - - `"incomplete"` + - `timezone: optional string` - - `ShellCallOutput object { call_id, output, type, 5 more }` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The streamed output items emitted by a shell tool call. + - `type: optional "approximate"` - - `call_id: string` + The type of location approximation. Always `approximate`. - The unique ID of the shell tool call generated by the model. + - `"approximate"` - - `output: array of BetaResponseFunctionShellCallOutputContent` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - Captured chunks of stdout and stderr output, along with their associated outcomes. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `outcome: object { type } or object { exit_code, type }` + - `server_label: string` - The exit or timeout outcome associated with this shell call. + A label for this MCP server, used to identify it in tool calls. - - `stderr: string` + - `type: "mcp"` - Captured stderr output for the shell call. + The type of the MCP tool. Always `mcp`. - - `stdout: string` + - `"mcp"` - Captured stdout output for the shell call. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "shell_call_output"` + The tool invocation context(s). - The type of the item. Always `shell_call_output`. + - `"direct"` - - `"shell_call_output"` + - `"programmatic"` - - `id: optional string` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - The unique ID of the shell tool call output. Populated when this item is returned via API. + List of allowed tool names or a filter object. - - `agent: optional object { agent_name }` + - `McpAllowedTools = array of string` - The agent that produced this item. + A string array of allowed tool names - - `agent_name: string` + - `McpToolFilter object { read_only, tool_names }` - The canonical name of the agent that produced this item. + 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, 4 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"` - - `agent: optional object { agent_name }` + - `file_ids: optional array of string` - The agent that produced this item. + An optional list of uploaded files to make available to your code. - - `agent_name: string` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The canonical name of the agent that produced this item. + The memory limit for the code interpreter container. - - `caller: optional object { type } or object { caller_id, type }` + - `"1g"` - The execution context that produced this tool call. + - `"4g"` - - `Direct object { type }` + - `"16g"` - - `type: "direct"` + - `"64g"` - The caller type. Always `direct`. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `"direct"` + Network access policy for the container. - - `Program object { caller_id, type }` + - `BetaContainerNetworkPolicyDisabled object { type }` - - `caller_id: string` + - `type: "disabled"` - The call ID of the program item that produced this tool call. + Disable outbound network access. Always `disabled`. - - `type: "program"` + - `"disabled"` - The caller type. Always `program`. + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `"program"` + - `allowed_domains: array of string` - - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` + A list of allowed domains when type is `allowlist`. - The streamed output emitted by an apply patch tool call. + - `type: "allowlist"` - - `call_id: string` + Allow outbound network access only to specified domains. Always `allowlist`. - The unique ID of the apply patch tool call generated by the model. + - `"allowlist"` - - `status: "completed" or "failed"` + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - The status of the apply patch tool call output. One of `completed` or `failed`. + Optional domain-scoped secrets for allowlisted domains. - - `"completed"` + - `domain: string` - - `"failed"` + The domain associated with the secret. - - `type: "apply_patch_call_output"` + - `name: string` - The type of the item. Always `apply_patch_call_output`. + The name of the secret to inject for the domain. - - `"apply_patch_call_output"` + - `value: string` - - `id: optional string` + The secret value to inject for the domain. - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + - `type: "code_interpreter"` - - `agent: optional object { agent_name }` + The type of the code interpreter tool. Always `code_interpreter`. - The agent that produced this item. + - `"code_interpreter"` - - `agent_name: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The canonical name of the agent that produced this item. + 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 }` + - `ProgrammaticToolCalling object { type }` - - `type: "direct"` + - `type: "programmatic_tool_calling"` - The caller type. Always `direct`. + The type of the tool. Always `programmatic_tool_calling`. - - `"direct"` + - `"programmatic_tool_calling"` - - `Program object { caller_id, type }` + - `ImageGeneration object { type, action, background, 9 more }` - - `caller_id: string` + A tool that generates images using the GPT image models. - The call ID of the program item that produced this tool call. + - `type: "image_generation"` - - `type: "program"` + The type of the image generation tool. Always `image_generation`. - The caller type. Always `program`. + - `"image_generation"` - - `"program"` + - `action: optional "generate" or "edit" or "auto"` - - `output: optional string` + Whether to generate a new image or edit an existing image. Default: `auto`. - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + - `"generate"` - - `McpListTools object { id, server_label, tools, 3 more }` + - `"edit"` - A list of tools available on an MCP server. + - `"auto"` - - `id: string` + - `background: optional "transparent" or "opaque" or "auto"` - The unique ID of the list. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `server_label: string` + - `"transparent"` - The label of the MCP server. + - `"opaque"` - - `tools: array of object { input_schema, name, annotations, description }` + - `"auto"` - The tools available on the server. + - `input_fidelity: optional "high" or "low"` - - `input_schema: unknown` + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - The JSON schema describing the tool's input. + - `"high"` - - `name: string` + - `"low"` - The name of the tool. + - `input_image_mask: optional object { file_id, image_url }` - - `annotations: optional unknown` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - Additional annotations about the tool. + - `file_id: optional string` - - `description: optional string` + File ID for the mask image. - The description of the tool. + - `image_url: optional string` - - `type: "mcp_list_tools"` + Base64-encoded mask image. - The type of the item. Always `mcp_list_tools`. + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `"mcp_list_tools"` + The image generation model to use. Default: `gpt-image-1`. - - `agent: optional object { agent_name }` + - `string` - The agent that produced this item. + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `agent_name: string` + The image generation model to use. Default: `gpt-image-1`. - The canonical name of the agent that produced this item. + - `"gpt-image-1"` - - `error: optional string` + - `"gpt-image-1-mini"` - Error message if the server could not list tools. + - `"gpt-image-1.5"` - - `McpApprovalRequest object { id, arguments, name, 3 more }` + - `moderation: optional "auto" or "low"` - A request for human approval of a tool invocation. + Moderation level for the generated image. Default: `auto`. - - `id: string` + - `"auto"` - The unique ID of the approval request. + - `"low"` - - `arguments: string` + - `output_compression: optional number` - A JSON string of arguments for the tool. + Compression level for the output image. Default: 100. - - `name: string` + - `output_format: optional "png" or "webp" or "jpeg"` - The name of the tool to run. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `server_label: string` + - `"png"` - The label of the MCP server making the request. + - `"webp"` - - `type: "mcp_approval_request"` + - `"jpeg"` - The type of the item. Always `mcp_approval_request`. + - `partial_images: optional number` - - `"mcp_approval_request"` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `agent: optional object { agent_name }` + - `quality: optional "low" or "medium" or "high" or "auto"` - The agent that produced this item. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `agent_name: string` + - `"low"` - The canonical name of the agent that produced this item. + - `"medium"` - - `McpApprovalResponse object { approval_request_id, approve, type, 3 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"` - - `agent: optional object { agent_name }` + - `LocalShell object { type }` - The agent that produced this item. + A tool that allows the model to execute shell commands in a local environment. - - `agent_name: string` + - `type: "local_shell"` - The canonical name of the agent that produced this item. + The type of the local shell tool. Always `local_shell`. - - `reason: optional string` + - `"local_shell"` - Optional reason for the decision. + - `Shell object { type, allowed_callers, environment }` - - `McpCall object { id, arguments, name, 7 more }` + A tool that allows the model to execute shell commands. - An invocation of a tool on an MCP server. + - `type: "shell"` - - `id: string` + The type of the shell tool. Always `shell`. - The unique ID of the tool call. + - `"shell"` - - `arguments: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - A JSON string of the arguments passed to the tool. + The tool invocation context(s). - - `name: string` + - `"direct"` - The name of the tool that was run. + - `"programmatic"` - - `server_label: string` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - The label of the MCP server running the tool. + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `type: "mcp_call"` + - `type: "container_auto"` - The type of the item. Always `mcp_call`. + Automatically creates a container for this request - - `"mcp_call"` + - `"container_auto"` - - `agent: optional object { agent_name }` + - `file_ids: optional array of string` - The agent that produced this item. + An optional list of uploaded files to make available to your code. - - `agent_name: string` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The canonical name of the agent that produced this item. + The memory limit for the container. - - `approval_request_id: optional string` + - `"1g"` - 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. + - `"4g"` - - `error: optional string` + - `"16g"` - The error from the tool call, if any. + - `"64g"` - - `output: optional string` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - The output from the tool call. + Network access policy for the container. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `BetaContainerNetworkPolicyDisabled object { type }` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `"in_progress"` + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - - `"completed"` + An optional list of skills referenced by id or inline data. - - `"incomplete"` + - `BetaSkillReference object { skill_id, type, version }` - - `"calling"` + - `skill_id: string` - - `"failed"` + The ID of the referenced skill. - - `CustomToolCallOutput object { call_id, output, type, 3 more }` + - `type: "skill_reference"` - The output of a custom tool call from your code, being sent back to the model. + References a skill created with the /v1/skills endpoint. - - `call_id: string` + - `"skill_reference"` - The call ID, used to map this custom tool call output to a custom tool call. + - `version: optional string` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + - `BetaInlineSkill object { description, name, source, type }` - - `StringOutput = string` + - `description: string` - A string of the output of the custom tool call. + The description of the skill. - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `name: string` - Text, image, or file output of the custom tool call. + The name of the skill. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `source: BetaInlineSkillSource` - A text input to the model. + Inline skill payload - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `data: string` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + Base64-encoded skill zip bundle. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `media_type: "application/zip"` - A file input to the model. + The media type of the inline skill payload. Must be `application/zip`. - - `type: "custom_tool_call_output"` + - `"application/zip"` - The type of the custom tool call output. Always `custom_tool_call_output`. + - `type: "base64"` - - `"custom_tool_call_output"` + The type of the inline skill source. Must be `base64`. - - `id: optional string` + - `"base64"` - The unique ID of the custom tool call output in the OpenAI platform. + - `type: "inline"` - - `agent: optional object { agent_name }` + Defines an inline skill for this request. - The agent that produced this item. + - `"inline"` - - `agent_name: string` + - `BetaLocalEnvironment object { type, skills }` - The canonical name of the agent that produced this item. + - `type: "local"` - - `caller: optional object { type } or object { caller_id, type }` + Use a local computer environment. - The execution context that produced this tool call. + - `"local"` - - `Direct object { type }` + - `skills: optional array of BetaLocalSkill` - - `type: "direct"` + An optional list of skills. - The caller type. Always `direct`. + - `description: string` - - `"direct"` + The description of the skill. - - `Program object { caller_id, type }` + - `name: string` - - `caller_id: string` + The name of the skill. - The call ID of the program item that produced this tool call. + - `path: string` - - `type: "program"` + The path to the directory containing the skill. - The caller type. Always `program`. + - `BetaContainerReference object { container_id, type }` - - `"program"` + - `container_id: string` - - `CustomToolCall object { call_id, input, name, 5 more }` + The ID of the referenced container. - A call to a custom tool created by the model. + - `type: "container_reference"` - - `call_id: string` + References a container created with the /v1/containers endpoint - An identifier used to map this custom tool call to a tool call output. + - `"container_reference"` - - `input: string` + - `Custom object { name, type, allowed_callers, 3 more }` - The input for the custom 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 custom tool being called. - - - `type: "custom_tool_call"` + The name of the custom tool, used to identify it in tool calls. - The type of the custom tool call. Always `custom_tool_call`. + - `type: "custom"` - - `"custom_tool_call"` + The type of the custom tool. Always `custom`. - - `id: optional string` + - `"custom"` - The unique ID of the custom tool call in the OpenAI platform. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `agent: optional object { agent_name }` + The tool invocation context(s). - The agent that produced this item. + - `"direct"` - - `agent_name: string` + - `"programmatic"` - The canonical name of the agent that produced this item. + - `defer_loading: optional boolean` - - `caller: optional object { type } or object { caller_id, type }` + Whether this tool should be deferred and discovered via tool search. - The execution context that produced this tool call. + - `description: optional string` - - `Direct object { type }` + Optional description of the custom tool, used to provide more context. - - `type: "direct"` + - `format: optional object { type } or object { definition, syntax, type }` - - `"direct"` + The input format for the custom tool. Default is unconstrained text. - - `Program object { caller_id, type }` + - `Text object { type }` - - `caller_id: string` + Unconstrained free-form text. - The call ID of the program item that produced this tool call. + - `type: "text"` - - `type: "program"` + Unconstrained text format. Always `text`. - - `"program"` + - `"text"` - - `namespace: optional string` + - `Grammar object { definition, syntax, type }` - The namespace of the custom tool being called. + A grammar defined by the user. - - `CompactionTrigger object { type, agent }` + - `definition: string` - Compacts the current context. Must be the final input item. + The grammar definition. - - `type: "compaction_trigger"` + - `syntax: "lark" or "regex"` - The type of the item. Always `compaction_trigger`. + The syntax of the grammar definition. One of `lark` or `regex`. - - `"compaction_trigger"` + - `"lark"` - - `agent: optional object { agent_name }` + - `"regex"` - The agent that produced this item. + - `type: "grammar"` - - `agent_name: string` + Grammar format. Always `grammar`. - The canonical name of the agent that produced this item. + - `"grammar"` - - `ItemReference object { id, agent, type }` + - `Namespace object { description, name, tools, type }` - An internal identifier for an item to reference. + Groups function/custom tools under a shared namespace. - - `id: string` + - `description: string` - The ID of the item to reference. + A description of the namespace shown to the model. - - `agent: optional object { agent_name }` + - `name: string` - The agent that produced this item. + The namespace name used in tool calls (for example, `crm`). - - `agent_name: string` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - The canonical name of the agent that produced this item. + The function/custom tools available inside this namespace. - - `type: optional "item_reference"` + - `Function object { name, type, allowed_callers, 5 more }` - The type of item to reference. Always `item_reference`. + - `name: string` - - `"item_reference"` + - `type: "function"` - - `Program object { id, call_id, code, 3 more }` + - `"function"` - - `id: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The unique ID of this program item. + The tool invocation context(s). - - `call_id: string` + - `"direct"` - The stable call ID of the program item. + - `"programmatic"` - - `code: string` + - `defer_loading: optional boolean` - The JavaScript source executed by programmatic tool calling. + Whether this function should be deferred and discovered via tool search. - - `fingerprint: string` + - `description: optional string` - Opaque program replay fingerprint that must be round-tripped. + - `output_schema: optional map[unknown]` - - `type: "program"` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - The item type. Always `program`. + - `parameters: optional unknown` - - `"program"` + - `strict: optional boolean` - - `agent: optional object { agent_name }` + 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 agent that produced this item. + - `Custom object { name, type, allowed_callers, 3 more }` - - `agent_name: string` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - The canonical name of the agent that produced this item. + - `name: string` - - `ProgramOutput object { id, call_id, result, 3 more }` + The name of the custom tool, used to identify it in tool calls. - - `id: string` + - `type: "custom"` - The unique ID of this program output item. + The type of the custom tool. Always `custom`. - - `call_id: string` + - `"custom"` - The call ID of the program item. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `result: string` + The tool invocation context(s). - The result produced by the program item. + - `"direct"` - - `status: "completed" or "incomplete"` + - `"programmatic"` - The terminal status of the program output. + - `defer_loading: optional boolean` - - `"completed"` + Whether this tool should be deferred and discovered via tool search. - - `"incomplete"` + - `description: optional string` - - `type: "program_output"` + Optional description of the custom tool, used to provide more context. - The item type. Always `program_output`. + - `format: optional object { type } or object { definition, syntax, type }` - - `"program_output"` + The input format for the custom tool. Default is unconstrained text. - - `agent: optional object { agent_name }` + - `Text object { type }` - The agent that produced this item. + Unconstrained free-form text. - - `agent_name: string` + - `type: "text"` - The canonical name of the agent that produced this item. + Unconstrained text format. Always `text`. - - `response_id: string` + - `"text"` - The ID of the active response that should receive the input. + - `Grammar object { definition, syntax, type }` - - `type: "response.inject"` + A grammar defined by the user. - The event discriminator. Always `response.inject`. + - `definition: string` - - `"response.inject"` + The grammar definition. -### Beta Responses Server Event + - `syntax: "lark" or "regex"` -- `BetaResponsesServerEvent = BetaResponseAudioDeltaEvent or BetaResponseAudioDoneEvent or BetaResponseAudioTranscriptDeltaEvent or 52 more` + The syntax of the grammar definition. One of `lark` or `regex`. - Server events emitted by the Responses WebSocket server. + - `"lark"` - - `BetaResponseAudioDeltaEvent object { delta, sequence_number, type, agent }` + - `"regex"` - Emitted when there is a partial audio response. + - `type: "grammar"` - - `delta: string` + Grammar format. Always `grammar`. - A chunk of Base64 encoded response audio bytes. + - `"grammar"` - - `sequence_number: number` + - `type: "namespace"` - A sequence number for this chunk of the stream response. + The type of the tool. Always `namespace`. - - `type: "response.audio.delta"` + - `"namespace"` - The type of the event. Always `response.audio.delta`. + - `ToolSearch object { type, description, execution, parameters }` - - `"response.audio.delta"` + Hosted or BYOT tool search configuration for deferred tools. - - `agent: optional object { agent_name }` + - `type: "tool_search"` - The agent that owns this multi-agent streaming event. + The type of the tool. Always `tool_search`. - - `agent_name: string` + - `"tool_search"` - The canonical name of the agent that produced this item. + - `description: optional string` - - `BetaResponseAudioDoneEvent object { sequence_number, type, agent }` + Description shown to the model for a client-executed tool search tool. - Emitted when the audio response is complete. + - `execution: optional "server" or "client"` - - `sequence_number: number` + Whether tool search is executed by the server or by the client. - The sequence number of the delta. + - `"server"` - - `type: "response.audio.done"` + - `"client"` - The type of the event. Always `response.audio.done`. + - `parameters: optional unknown` - - `"response.audio.done"` + Parameter schema for a client-executed tool search tool. - - `agent: optional object { agent_name }` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - The agent that owns this multi-agent streaming event. + 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). - - `agent_name: string` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - The canonical name of the agent that produced this item. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `BetaResponseAudioTranscriptDeltaEvent object { delta, sequence_number, type, agent }` + - `"web_search_preview"` - Emitted when there is a partial transcript of audio. + - `"web_search_preview_2025_03_11"` - - `delta: string` + - `search_content_types: optional array of "text" or "image"` - The partial transcript of the audio response. + - `"text"` - - `sequence_number: number` + - `"image"` - The sequence number of this event. + - `search_context_size: optional "low" or "medium" or "high"` - - `type: "response.audio.transcript.delta"` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - The type of the event. Always `response.audio.transcript.delta`. + - `"low"` - - `"response.audio.transcript.delta"` + - `"medium"` - - `agent: optional object { agent_name }` + - `"high"` - The agent that owns this multi-agent streaming event. + - `user_location: optional object { type, city, country, 2 more }` - - `agent_name: string` + The user's location. - The canonical name of the agent that produced this item. + - `type: "approximate"` - - `BetaResponseAudioTranscriptDoneEvent object { sequence_number, type, agent }` + The type of location approximation. Always `approximate`. - Emitted when the full audio transcript is completed. + - `"approximate"` - - `sequence_number: number` + - `city: optional string` - The sequence number of this event. + Free text input for the city of the user, e.g. `San Francisco`. - - `type: "response.audio.transcript.done"` + - `country: optional string` - The type of the event. Always `response.audio.transcript.done`. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"response.audio.transcript.done"` + - `region: optional string` - - `agent: optional object { agent_name }` + Free text input for the region of the user, e.g. `California`. - The agent that owns this multi-agent streaming event. + - `timezone: optional string` - - `agent_name: string` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The canonical name of the agent that produced this item. + - `ApplyPatch object { type, allowed_callers }` - - `BetaResponseCodeInterpreterCallCodeDeltaEvent object { delta, item_id, output_index, 3 more }` + Allows the assistant to create, delete, or update files using unified diffs. - Emitted when a partial code snippet is streamed by the code interpreter. + - `type: "apply_patch"` - - `delta: string` + The type of the tool. Always `apply_patch`. - The partial code snippet being streamed by the code interpreter. + - `"apply_patch"` - - `item_id: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The unique identifier of the code interpreter tool call item. + The tool invocation context(s). - - `output_index: number` + - `"direct"` - The index of the output item in the response for which the code is being streamed. + - `"programmatic"` - - `sequence_number: number` + - `type: "tool_search_output"` - The sequence number of this event, used to order streaming events. + The item type. Always `tool_search_output`. - - `type: "response.code_interpreter_call_code.delta"` + - `"tool_search_output"` - The type of the event. Always `response.code_interpreter_call_code.delta`. + - `id: optional string` - - `"response.code_interpreter_call_code.delta"` + The unique ID of this tool search output. - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. - - `BetaResponseCodeInterpreterCallCodeDoneEvent object { code, item_id, output_index, 3 more }` - - Emitted when the code snippet is finalized by the code interpreter. - - - `code: string` - - The final code snippet output by the code interpreter. - - - `item_id: string` - - The unique identifier of the code interpreter tool call item. + - `call_id: optional string` - - `output_index: number` + The unique ID of the tool search call generated by the model. - The index of the output item in the response for which the code is finalized. + - `execution: optional "server" or "client"` - - `sequence_number: number` + Whether tool search was executed by the server or by the client. - The sequence number of this event, used to order streaming events. + - `"server"` - - `type: "response.code_interpreter_call_code.done"` + - `"client"` - The type of the event. Always `response.code_interpreter_call_code.done`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"response.code_interpreter_call_code.done"` + The status of the tool search output. - - `agent: optional object { agent_name }` + - `"in_progress"` - The agent that owns this multi-agent streaming event. + - `"completed"` - - `agent_name: string` + - `"incomplete"` - The canonical name of the agent that produced this item. + - `AdditionalTools object { role, tools, type, 2 more }` - - `BetaResponseCodeInterpreterCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` + - `role: "developer"` - Emitted when the code interpreter call is completed. + The role that provided the additional tools. Only `developer` is supported. - - `item_id: string` + - `"developer"` - The unique identifier of the code interpreter tool call item. + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - - `output_index: number` + A list of additional tools made available at this item. - The index of the output item in the response for which the code interpreter call is completed. + - `Function object { name, parameters, strict, 5 more }` - - `sequence_number: number` + 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 sequence number of this event, used to order streaming events. + - `name: string` - - `type: "response.code_interpreter_call.completed"` + The name of the function to call. - The type of the event. Always `response.code_interpreter_call.completed`. + - `parameters: map[unknown]` - - `"response.code_interpreter_call.completed"` + A JSON schema object describing the parameters of the function. - - `agent: optional object { agent_name }` + - `strict: boolean` - The agent that owns this multi-agent streaming event. + Whether strict parameter validation is enforced for this function tool. - - `agent_name: string` + - `type: "function"` - The canonical name of the agent that produced this item. + The type of the function tool. Always `function`. - - `BetaResponseCodeInterpreterCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + - `"function"` - Emitted when a code interpreter call is in progress. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `item_id: string` + The tool invocation context(s). - The unique identifier of the code interpreter tool call item. + - `"direct"` - - `output_index: number` + - `"programmatic"` - The index of the output item in the response for which the code interpreter call is in progress. + - `defer_loading: optional boolean` - - `sequence_number: number` + Whether this function is deferred and loaded via tool search. - The sequence number of this event, used to order streaming events. + - `description: optional string` - - `type: "response.code_interpreter_call.in_progress"` + A description of the function. Used by the model to determine whether or not to call the function. - The type of the event. Always `response.code_interpreter_call.in_progress`. + - `output_schema: optional map[unknown]` - - `"response.code_interpreter_call.in_progress"` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `agent: optional object { agent_name }` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - The agent that owns this multi-agent streaming event. + 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). - - `agent_name: string` + - `type: "file_search"` - The canonical name of the agent that produced this item. + The type of the file search tool. Always `file_search`. - - `BetaResponseCodeInterpreterCallInterpretingEvent object { item_id, output_index, sequence_number, 2 more }` + - `"file_search"` - Emitted when the code interpreter is actively interpreting the code snippet. + - `vector_store_ids: array of string` - - `item_id: string` + The IDs of the vector stores to search. - The unique identifier of the code interpreter tool call item. + - `filters: optional object { key, type, value } or object { filters, type }` - - `output_index: number` + A filter to apply. - The index of the output item in the response for which the code interpreter is interpreting code. + - `ComparisonFilter object { key, type, value }` - - `sequence_number: number` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The sequence number of this event, used to order streaming events. + - `key: string` - - `type: "response.code_interpreter_call.interpreting"` + The key to compare against the value. - The type of the event. Always `response.code_interpreter_call.interpreting`. + - `type: "eq" or "ne" or "gt" or 5 more` - - `"response.code_interpreter_call.interpreting"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `agent: optional object { agent_name }` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - The agent that owns this multi-agent streaming event. + - `"eq"` - - `agent_name: string` + - `"ne"` - The canonical name of the agent that produced this item. + - `"gt"` - - `BetaResponseCompletedEvent object { response, sequence_number, type, agent }` + - `"gte"` - Emitted when the model response is complete. + - `"lt"` - - `response: BetaResponse` + - `"lte"` - Properties of the completed response. + - `"in"` - - `id: string` + - `"nin"` - Unique identifier for this Response. + - `value: string or number or boolean or array of string or number` - - `created_at: number` + The value to compare against the attribute key; supports string, number, or boolean types. - Unix timestamp (in seconds) of when this Response was created. + - `string` - - `error: BetaResponseError` + - `number` - An error object returned when the model fails to generate a Response. + - `boolean` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 17 more` + - `array of string or number` - The error code for the response. + - `string` - - `"server_error"` + - `number` - - `"rate_limit_exceeded"` + - `CompoundFilter object { filters, type }` - - `"invalid_prompt"` + Combine multiple filters using `and` or `or`. - - `"data_residency_mismatch"` + - `filters: array of object { key, type, value } or unknown` - - `"bio_policy"` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `"vector_store_timeout"` + - `ComparisonFilter object { key, type, value }` - - `"invalid_image"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"invalid_image_format"` + - `key: string` - - `"invalid_base64_image"` + The key to compare against the value. - - `"invalid_image_url"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `"image_too_large"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"image_too_small"` + - `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 - - `"image_parse_error"` + - `"eq"` - - `"image_content_policy_violation"` + - `"ne"` - - `"invalid_image_mode"` + - `"gt"` - - `"image_file_too_large"` + - `"gte"` - - `"unsupported_image_media_type"` + - `"lt"` - - `"empty_image_file"` + - `"lte"` - - `"failed_to_download_image"` + - `"in"` - - `"image_file_not_found"` + - `"nin"` - - `message: string` + - `value: string or number or boolean or array of string or number` - A human-readable description of the error. + The value to compare against the attribute key; supports string, number, or boolean types. - - `incomplete_details: object { reason }` + - `string` - Details about why the response is incomplete. + - `number` - - `reason: optional "max_output_tokens" or "content_filter"` + - `boolean` - The reason why the response is incomplete. + - `array of string or number` - - `"max_output_tokens"` + - `string` - - `"content_filter"` + - `number` - - `instructions: string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + - `unknown` - A system (or developer) message inserted into the model's context. + - `type: "and" or "or"` - 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. + Type of operation: `and` or `or`. - - `string` + - `"and"` - A text input to the model, equivalent to a text input with the - `developer` role. + - `"or"` - - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 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. - - `BetaEasyInputMessage 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 BetaResponseInputMessageContentList` + - `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. - - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` + - `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. - - `BetaResponseInputText 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 }` - - `BetaResponseInputImage 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"` - - `BetaResponseInputFile 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, agent, 2 more }` + - `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: BetaResponseInputMessageContentList` + - `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` - - `agent: optional object { agent_name }` + 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 agent that produced this item. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `agent_name: 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 canonical name of the agent that produced this item. + Currently supported `connector_id` values are: - - `status: optional "in_progress" or "completed" or "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` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"connector_dropbox"` - - `"in_progress"` + - `"connector_gmail"` - - `"completed"` + - `"connector_googlecalendar"` - - `"incomplete"` + - `"connector_googledrive"` - - `type: optional "message"` + - `"connector_microsoftteams"` - The type of the message input. Always set to `message`. + - `"connector_outlookcalendar"` - - `"message"` + - `"connector_outlookemail"` - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + - `"connector_sharepoint"` - An output message from the model. + - `defer_loading: optional boolean` - - `id: string` + Whether this MCP tool is deferred and discovered via tool search. - The unique ID of the output message. + - `headers: optional map[string]` - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The content of the output message. + - `require_approval: optional object { always, never } or "always" or "never"` - - `BetaResponseOutputText object { annotations, logprobs, text, type }` + Specify which of the MCP server's tools require approval. - A text output from the model. + - `McpToolApprovalFilter object { always, never }` - - `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 }` + 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 annotations of the text output. + - `always: optional object { read_only, tool_names }` - - `FileCitation object { file_id, filename, index, type }` + A filter object to specify which tools are allowed. - A citation to a file. + - `read_only: optional boolean` - - `file_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 file. + - `tool_names: optional array of string` - - `filename: string` + List of allowed tool names. - The filename of the file cited. + - `never: optional object { read_only, tool_names }` - - `index: number` + A filter object to specify which tools are allowed. - The index of the file in the list of files. + - `read_only: optional boolean` - - `type: "file_citation"` + 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 file citation. Always `file_citation`. + - `tool_names: optional array of string` - - `"file_citation"` + List of allowed tool names. - - `URLCitation object { end_index, start_index, title, 2 more }` + - `McpToolApprovalSetting = "always" or "never"` - A citation for a web resource used to generate a model response. + 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. - - `end_index: number` + - `"always"` - The index of the last character of the URL citation in the message. + - `"never"` - - `start_index: number` + - `server_description: optional string` - The index of the first character of the URL citation in the message. + Optional description of the MCP server, used to provide more context. - - `title: string` + - `server_url: optional string` - The title of the web resource. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `type: "url_citation"` + - `tunnel_id: optional string` - The type of the URL citation. Always `url_citation`. + 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. - - `"url_citation"` + - `CodeInterpreter object { container, type, allowed_callers }` - - `url: string` + A tool that runs Python code to help generate a response to a prompt. - The URL of the web resource. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 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 citation for a container file used to generate a model response. + - `string` - - `container_id: string` + The container ID. - The ID of the container file. + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `end_index: number` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The index of the last character of the container file citation in the message. + - `type: "auto"` - - `file_id: string` + Always `auto`. - The ID of the file. + - `"auto"` - - `filename: string` + - `file_ids: optional array of string` - The filename of the container file cited. + An optional list of uploaded files to make available to your code. - - `start_index: number` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The index of the first character of the container file citation in the message. + The memory limit for the code interpreter container. - - `type: "container_file_citation"` + - `"1g"` - The type of the container file citation. Always `container_file_citation`. + - `"4g"` - - `"container_file_citation"` + - `"16g"` - - `FilePath object { file_id, index, type }` + - `"64g"` - A path to a file. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `file_id: string` + Network access policy for the container. - The ID of the file. + - `BetaContainerNetworkPolicyDisabled object { type }` - - `index: number` + - `BetaContainerNetworkPolicyAllowlist 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"` - - `BetaResponseOutputRefusal object { refusal, type }` + Whether to generate a new image or edit an existing image. Default: `auto`. - A refusal from the model. + - `"generate"` - - `refusal: string` + - `"edit"` - The refusal explanation from the model. + - `"auto"` - - `type: "refusal"` + - `background: optional "transparent" or "opaque" or "auto"` - The type of the refusal. Always `refusal`. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `"refusal"` + - `"transparent"` - - `role: "assistant"` + - `"opaque"` - The role of the output message. Always `assistant`. + - `"auto"` - - `"assistant"` + - `input_fidelity: optional "high" or "low"` - - `status: "in_progress" or "completed" or "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`. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `"high"` - - `"in_progress"` + - `"low"` - - `"completed"` + - `input_image_mask: optional object { file_id, image_url }` - - `"incomplete"` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `type: "message"` + - `file_id: optional string` - The type of the output message. Always `message`. + File ID for the mask image. - - `"message"` + - `image_url: optional string` - - `agent: optional object { agent_name }` + Base64-encoded mask image. - The agent that produced this item. + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `agent_name: string` + The image generation model to use. Default: `gpt-image-1`. - The canonical name of the agent that produced this item. + - `string` - - `phase: optional "commentary" or "final_answer"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - 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 image generation model to use. Default: `gpt-image-1`. - - `"commentary"` + - `"gpt-image-1"` - - `"final_answer"` + - `"gpt-image-1-mini"` - - `FileSearchCall object { id, queries, status, 3 more }` + - `"gpt-image-1.5"` - The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + - `moderation: optional "auto" or "low"` - - `id: string` + Moderation level for the generated image. Default: `auto`. - The unique ID of the file search tool call. + - `"auto"` - - `queries: array of string` + - `"low"` - The queries used to search for files. + - `output_compression: optional number` - - `status: "in_progress" or "searching" or "completed" or 2 more` + Compression level for the output image. Default: 100. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `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`. - - `"searching"` + - `"png"` - - `"completed"` + - `"webp"` - - `"incomplete"` + - `"jpeg"` - - `"failed"` + - `partial_images: optional number` - - `type: "file_search_call"` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The type of the file search tool call. Always `file_search_call`. + - `quality: optional "low" or "medium" or "high" or "auto"` - - `"file_search_call"` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `agent: optional object { agent_name }` + - `"low"` - The agent that produced this item. + - `"medium"` - - `agent_name: string` + - `"high"` - The canonical name of the agent that produced this item. + - `"auto"` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - The results of the file search tool call. + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - - `attributes: optional map[string or number or boolean]` + - `string` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `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`. - - `number` + - `"1024x1024"` - - `boolean` + - `"1024x1536"` - - `file_id: optional string` + - `"1536x1024"` - The unique ID of the file. + - `"auto"` - - `filename: optional string` + - `LocalShell object { type }` - The name of the file. + A tool that allows the model to execute shell commands in a local environment. - - `score: optional number` + - `type: "local_shell"` - The relevance score of the file - a value between 0 and 1. + The type of the local shell tool. Always `local_shell`. - - `text: optional string` + - `"local_shell"` - The text that was retrieved from the file. + - `Shell object { type, allowed_callers, environment }` - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + A tool that allows the model to execute shell commands. - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + - `type: "shell"` - - `id: string` + The type of the shell tool. Always `shell`. - The unique ID of the computer call. + - `"shell"` - - `call_id: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - An identifier used when responding to the tool call with output. + The tool invocation context(s). - - `pending_safety_checks: array of object { id, code, message }` + - `"direct"` - The pending safety checks for the computer call. + - `"programmatic"` - - `id: string` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - The ID of the pending safety check. + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `code: optional string` + - `BetaLocalEnvironment object { type, skills }` - The type of the pending safety check. + - `BetaContainerReference object { container_id, type }` - - `message: optional string` + - `Custom object { name, type, allowed_callers, 3 more }` - Details about the pending safety check. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `status: "in_progress" or "completed" or "incomplete"` + - `name: string` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The name of the custom tool, used to identify it in tool calls. - - `"in_progress"` + - `type: "custom"` - - `"completed"` + The type of the custom tool. Always `custom`. - - `"incomplete"` + - `"custom"` - - `type: "computer_call"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The type of the computer call. Always `computer_call`. + The tool invocation context(s). - - `"computer_call"` + - `"direct"` - - `action: optional BetaComputerAction` + - `"programmatic"` - A click action. + - `defer_loading: optional boolean` - - `Click object { button, type, x, 2 more }` + Whether this tool should be deferred and discovered via tool search. - A click action. + - `description: optional string` - - `button: "left" or "right" or "wheel" or 2 more` + Optional description of the custom tool, used to provide more context. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `format: optional object { type } or object { definition, syntax, type }` - - `"left"` + The input format for the custom tool. Default is unconstrained text. - - `"right"` + - `Text object { type }` - - `"wheel"` + Unconstrained free-form text. - - `"back"` + - `type: "text"` - - `"forward"` + Unconstrained text format. Always `text`. - - `type: "click"` + - `"text"` - Specifies the event type. For a click action, this property is always `click`. + - `Grammar object { definition, syntax, type }` - - `"click"` + A grammar defined by the user. - - `x: number` + - `definition: string` - The x-coordinate where the click occurred. + The grammar definition. - - `y: number` + - `syntax: "lark" or "regex"` - The y-coordinate where the click occurred. + The syntax of the grammar definition. One of `lark` or `regex`. - - `keys: optional array of string` + - `"lark"` - The keys being held while clicking. + - `"regex"` - - `DoubleClick object { keys, type, x, y }` + - `type: "grammar"` - A double click action. + Grammar format. Always `grammar`. - - `keys: array of string` + - `"grammar"` - The keys being held while double-clicking. + - `Namespace object { description, name, tools, type }` - - `type: "double_click"` + Groups function/custom tools under a shared namespace. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `description: string` - - `"double_click"` + A description of the namespace shown to the model. - - `x: number` + - `name: string` - The x-coordinate where the double click occurred. + The namespace name used in tool calls (for example, `crm`). - - `y: number` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - The y-coordinate where the double click occurred. + The function/custom tools available inside this namespace. - - `Drag object { path, type, keys }` + - `Function object { name, type, allowed_callers, 5 more }` - A drag action. + - `name: string` - - `path: array of object { x, y }` + - `type: "function"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `"function"` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `x: number` + The tool invocation context(s). - The x-coordinate. + - `"direct"` - - `y: number` + - `"programmatic"` - The y-coordinate. + - `defer_loading: optional boolean` - - `type: "drag"` + Whether this function should be deferred and discovered via tool search. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `description: optional string` - - `"drag"` + - `output_schema: optional map[unknown]` - - `keys: optional array of string` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - The keys being held while dragging the mouse. + - `parameters: optional unknown` - - `Keypress object { keys, type }` + - `strict: optional boolean` - A collection of keypresses the model would like to perform. + 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: array of string` + - `Custom object { name, type, allowed_callers, 3 more }` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `type: "keypress"` + - `name: string` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + The name of the custom tool, used to identify it in tool calls. - - `"keypress"` + - `type: "custom"` - - `Move object { type, x, y, keys }` + The type of the custom tool. Always `custom`. - A mouse move action. + - `"custom"` - - `type: "move"` + - `allowed_callers: optional array of "direct" or "programmatic"` - Specifies the event type. For a move action, this property is always set to `move`. + The tool invocation context(s). - - `"move"` + - `"direct"` - - `x: number` + - `"programmatic"` - The x-coordinate to move to. + - `defer_loading: optional boolean` - - `y: number` + Whether this tool should be deferred and discovered via tool search. - The y-coordinate to move to. + - `description: optional string` - - `keys: optional array of string` + Optional description of the custom tool, used to provide more context. - The keys being held while moving the mouse. + - `format: optional object { type } or object { definition, syntax, type }` - - `Screenshot object { type }` + The input format for the custom tool. Default is unconstrained text. - A screenshot action. + - `Text object { type }` - - `type: "screenshot"` + Unconstrained free-form text. - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `type: "text"` - - `"screenshot"` + Unconstrained text format. Always `text`. - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `"text"` - A scroll action. + - `Grammar object { definition, syntax, type }` - - `scroll_x: number` + A grammar defined by the user. - The horizontal scroll distance. + - `definition: string` - - `scroll_y: number` + The grammar definition. - The vertical scroll distance. + - `syntax: "lark" or "regex"` - - `type: "scroll"` + The syntax of the grammar definition. One of `lark` or `regex`. - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `"lark"` - - `"scroll"` + - `"regex"` - - `x: number` + - `type: "grammar"` - The x-coordinate where the scroll occurred. + Grammar format. Always `grammar`. - - `y: number` + - `"grammar"` - The y-coordinate where the scroll occurred. + - `type: "namespace"` - - `keys: optional array of string` + The type of the tool. Always `namespace`. - The keys being held while scrolling. + - `"namespace"` - - `Type object { text, type }` + - `ToolSearch object { type, description, execution, parameters }` - An action to type in text. + Hosted or BYOT tool search configuration for deferred tools. - - `text: string` + - `type: "tool_search"` - The text to type. + The type of the tool. Always `tool_search`. - - `type: "type"` + - `"tool_search"` - Specifies the event type. For a type action, this property is always set to `type`. + - `description: optional string` - - `"type"` + Description shown to the model for a client-executed tool search tool. - - `Wait object { type }` + - `execution: optional "server" or "client"` - A wait action. + Whether tool search is executed by the server or by the client. - - `type: "wait"` + - `"server"` - Specifies the event type. For a wait action, this property is always set to `wait`. + - `"client"` - - `"wait"` + - `parameters: optional unknown` - - `actions: optional BetaComputerActionList` + Parameter schema for a client-executed tool search tool. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `Click object { button, type, x, 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 click action. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `DoubleClick object { keys, type, x, y }` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - A double click action. + - `"web_search_preview"` - - `Drag object { path, type, keys }` + - `"web_search_preview_2025_03_11"` - A drag action. + - `search_content_types: optional array of "text" or "image"` - - `Keypress object { keys, type }` + - `"text"` - A collection of keypresses the model would like to perform. + - `"image"` - - `Move object { type, x, y, keys }` + - `search_context_size: optional "low" or "medium" or "high"` - A mouse move action. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `Screenshot object { type }` + - `"low"` - A screenshot action. + - `"medium"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `"high"` - A scroll action. + - `user_location: optional object { type, city, country, 2 more }` - - `Type object { text, type }` + The user's location. - An action to type in text. + - `type: "approximate"` - - `Wait object { type }` + The type of location approximation. Always `approximate`. - A wait action. + - `"approximate"` - - `agent: optional object { agent_name }` + - `city: optional string` - The agent that produced this item. + Free text input for the city of the user, e.g. `San Francisco`. - - `agent_name: string` + - `country: optional string` - The canonical name of the agent that produced this item. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `ComputerCallOutput object { call_id, output, type, 4 more }` + - `region: optional string` - The output of a computer tool call. + Free text input for the region of the user, e.g. `California`. - - `call_id: string` + - `timezone: optional string` - The ID of the computer tool call that produced the output. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `ApplyPatch object { type, allowed_callers }` - A computer screenshot image used with the computer use tool. + Allows the assistant to create, delete, or update files using unified diffs. - - `type: "computer_screenshot"` + - `type: "apply_patch"` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + The type of the tool. Always `apply_patch`. - - `"computer_screenshot"` + - `"apply_patch"` - - `file_id: optional string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The identifier of an uploaded file that contains the screenshot. + The tool invocation context(s). - - `image_url: optional string` + - `"direct"` - The URL of the screenshot image. + - `"programmatic"` - - `type: "computer_call_output"` + - `type: "additional_tools"` - The type of the computer tool call output. Always `computer_call_output`. + The item type. Always `additional_tools`. - - `"computer_call_output"` + - `"additional_tools"` - `id: optional string` - The ID of the computer tool call output. + The unique ID of this additional tools item. - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `agent: optional object { agent_name }` - The safety checks reported by the API that have been acknowledged by the developer. + The agent that produced this item. - - `id: string` + - `agent_name: string` - The ID of the pending safety check. + The canonical name of the agent that produced this item. - - `code: optional string` + - `Reasoning object { id, summary, type, 4 more }` - The type of the pending safety check. + 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). - - `message: optional string` + - `id: string` - Details about the pending safety check. + The unique identifier of the reasoning content. - - `agent: optional object { agent_name }` + - `summary: array of object { text, type }` - The agent that produced this item. + Reasoning summary content. - - `agent_name: string` + - `text: string` - The canonical name of the agent that produced this item. + A summary of the reasoning output from the model so far. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `type: "summary_text"` - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + The type of the object. Always `summary_text`. - - `"in_progress"` + - `"summary_text"` - - `"completed"` + - `type: "reasoning"` - - `"incomplete"` + The type of the object. Always `reasoning`. - - `WebSearchCall object { id, action, status, 2 more }` + - `"reasoning"` - The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + - `agent: optional object { agent_name }` - - `id: string` + The agent that produced this item. - The unique ID of the web search tool call. + - `agent_name: string` - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + The canonical name of the agent that produced this item. - 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). + - `content: optional array of object { text, type }` - - `Search object { type, queries, query, sources }` + Reasoning text content. - Action type "search" - Performs a web search query. + - `text: string` - - `type: "search"` + The reasoning text from the model. - The action type. + - `type: "reasoning_text"` - - `"search"` + The type of the reasoning text. Always `reasoning_text`. - - `queries: optional array of string` + - `"reasoning_text"` - The search queries. + - `encrypted_content: optional string` - - `query: 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 search query. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `sources: optional array of object { type, url }` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The sources used in the search. + - `"in_progress"` - - `type: "url"` + - `"completed"` - The type of source. Always `url`. + - `"incomplete"` - - `"url"` + - `Compaction object { encrypted_content, type, id, agent }` - - `url: string` + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - The URL of the source. + - `encrypted_content: string` - - `OpenPage object { type, url }` + The encrypted content of the compaction summary. - Action type "open_page" - Opens a specific URL from search results. + - `type: "compaction"` - - `type: "open_page"` + The type of the item. Always `compaction`. - The action type. + - `"compaction"` - - `"open_page"` + - `id: optional string` - - `url: optional string` + The ID of the compaction item. - The URL opened by the model. + - `agent: optional object { agent_name }` - - `FindInPage object { pattern, type, url }` + The agent that produced this item. - Action type "find_in_page": Searches for a pattern within a loaded page. + - `agent_name: string` - - `pattern: string` + The canonical name of the agent that produced this item. - The pattern or text to search for within the page. + - `ImageGenerationCall object { id, result, status, 2 more }` - - `type: "find_in_page"` + An image generation request made by the model. - The action type. + - `id: string` - - `"find_in_page"` + The unique ID of the image generation call. - - `url: string` + - `result: string` - The URL of the page searched for the pattern. + The generated image encoded in base64. - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `status: "in_progress" or "completed" or "generating" or "failed"` - The status of the web search tool call. + The status of the image generation call. - `"in_progress"` - - `"searching"` - - `"completed"` + - `"generating"` + - `"failed"` - - `type: "web_search_call"` + - `type: "image_generation_call"` - The type of the web search tool call. Always `web_search_call`. + The type of the image generation call. Always `image_generation_call`. - - `"web_search_call"` + - `"image_generation_call"` - `agent: optional object { agent_name }` @@ -183410,215 +183702,218 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `FunctionCall object { arguments, call_id, name, 6 more }` + - `CodeInterpreterCall object { id, code, container_id, 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 run code. - - `arguments: string` + - `id: string` - A JSON string of the arguments to pass to the function. + The unique ID of the code interpreter tool call. - - `call_id: string` + - `code: string` - The unique ID of the function tool call generated by the model. + The code to run, or null if not available. - - `name: string` + - `container_id: string` - The name of the function to run. + The ID of the container used to run the code. - - `type: "function_call"` + - `outputs: array of object { logs, type } or object { type, url }` - The type of the function tool call. Always `function_call`. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `"function_call"` + - `Logs object { logs, type }` - - `id: optional string` + The logs output from the code interpreter. - The unique ID of the function tool call. + - `logs: string` - - `agent: optional object { agent_name }` + The logs output from the code interpreter. - The agent that produced this item. + - `type: "logs"` - - `agent_name: string` + The type of the output. Always `logs`. - The canonical name of the agent that produced this item. + - `"logs"` - - `caller: optional object { type } or object { caller_id, type }` + - `Image object { type, url }` - The execution context that produced this tool call. + The image output from the code interpreter. - - `Direct object { type }` + - `type: "image"` - - `type: "direct"` + The type of the output. Always `image`. - - `"direct"` + - `"image"` - - `Program object { caller_id, type }` + - `url: string` - - `caller_id: string` + The URL of the image output from the code interpreter. - The call ID of the program item that produced this tool call. + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - `type: "program"` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `"program"` + - `"in_progress"` - - `namespace: optional string` + - `"completed"` - The namespace of the function to run. + - `"incomplete"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"interpreting"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"failed"` - - `"in_progress"` + - `type: "code_interpreter_call"` - - `"completed"` + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `"incomplete"` + - `"code_interpreter_call"` - - `FunctionCallOutput object { call_id, output, type, 4 more }` + - `agent: optional object { agent_name }` - The output of a function tool call. + The agent that produced this item. - - `call_id: string` + - `agent_name: string` - The unique ID of the function tool call generated by the model. + The canonical name of the agent that produced this item. - - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` + - `LocalShellCall object { id, action, call_id, 3 more }` - Text, image, or file output of the function tool call. + A tool call to run a command on the local shell. - - `string` + - `id: string` - A JSON string of the output of the function tool call. + The unique ID of the local shell call. - - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` + - `action: object { command, env, type, 3 more }` - An array of content outputs (text, image, file) for the function tool call. + Execute a shell command on the server. - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + - `command: array of string` - A text input to the model. + The command to run. - - `text: string` + - `env: map[string]` - The text input to the model. + Environment variables to set for the command. - - `type: "input_text"` + - `type: "exec"` - The type of the input item. Always `input_text`. + The type of the local shell action. Always `exec`. - - `"input_text"` + - `"exec"` - - `prompt_cache_breakpoint: optional object { mode }` + - `timeout_ms: optional number` - 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. + Optional timeout in milliseconds for the command. - - `mode: "explicit"` + - `user: optional string` - The breakpoint mode. Always `explicit`. + Optional user to run the command as. - - `"explicit"` + - `working_directory: optional string` - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + Optional working directory to run the command in. - An image input to the model. Learn about [image inputs](/docs/guides/vision) + - `call_id: string` - - `type: "input_image"` + The unique ID of the local shell tool call generated by the model. - The type of the input item. Always `input_image`. + - `status: "in_progress" or "completed" or "incomplete"` - - `"input_image"` + The status of the local shell call. - - `detail: optional "low" or "high" or "auto" or "original"` + - `"in_progress"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"completed"` - - `"low"` + - `"incomplete"` - - `"high"` + - `type: "local_shell_call"` - - `"auto"` + The type of the local shell call. Always `local_shell_call`. - - `"original"` + - `"local_shell_call"` - - `file_id: optional string` + - `agent: optional object { agent_name }` - The ID of the file to be sent to the model. + The agent that produced this item. - - `image_url: optional string` + - `agent_name: 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 canonical name of the agent that produced this item. - - `prompt_cache_breakpoint: optional object { mode }` + - `LocalShellCallOutput object { id, output, type, 2 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 local shell tool call. - - `mode: "explicit"` + - `id: string` - The breakpoint mode. Always `explicit`. + The unique ID of the local shell tool call generated by the model. - - `"explicit"` + - `output: string` - - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` + A JSON string of the output of the local shell tool call. - A file input to the model. + - `type: "local_shell_call_output"` - - `type: "input_file"` + The type of the local shell tool call output. Always `local_shell_call_output`. - The type of the input item. Always `input_file`. + - `"local_shell_call_output"` - - `"input_file"` + - `agent: optional object { agent_name }` - - `detail: optional "auto" or "low" or "high"` + The agent that produced this item. - 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`. + - `agent_name: string` - - `"auto"` + The canonical name of the agent that produced this item. - - `"low"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"high"` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `file_data: optional string` + - `"in_progress"` - The base64-encoded data of the file to be sent to the model. + - `"completed"` - - `file_id: optional string` + - `"incomplete"` - The ID of the file to be sent to the model. + - `ShellCall object { action, call_id, type, 5 more }` - - `file_url: optional string` + A tool representing a request to execute one or more shell commands. - The URL of the file to be sent to the model. + - `action: object { commands, max_output_length, timeout_ms }` - - `filename: optional string` + The shell commands and limits that describe how to run the tool call. - The name of the file to be sent to the model. + - `commands: array of string` - - `prompt_cache_breakpoint: optional object { mode }` + Ordered shell commands for the execution environment to run. - 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. + - `max_output_length: optional number` - - `mode: "explicit"` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - The breakpoint mode. Always `explicit`. + - `timeout_ms: optional number` - - `"explicit"` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `type: "function_call_output"` + - `call_id: string` - The type of the function tool call output. Always `function_call_output`. + The unique ID of the shell tool call generated by the model. - - `"function_call_output"` + - `type: "shell_call"` + + The type of the item. Always `shell_call`. + + - `"shell_call"` - `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 shell tool call. Populated when this item is returned via API. - `agent: optional object { agent_name }` @@ -183652,107 +183947,81 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"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"` - - - `AgentMessage object { author, content, recipient, 3 more }` - - A message routed between agents. - - - `author: string` - - The sending agent identity. - - - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - - Plaintext, image, or encrypted content sent between agents. - - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + - `environment: optional BetaLocalEnvironment or BetaContainerReference` - An image input to the model. Learn about [image inputs](/docs/guides/vision) + The environment to execute the shell commands in. - - `EncryptedContent object { encrypted_content, type }` + - `BetaLocalEnvironment object { type, skills }` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `BetaContainerReference object { container_id, type }` - - `encrypted_content: string` + - `status: optional "in_progress" or "completed" or "incomplete"` - Opaque encrypted content. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - - `type: "encrypted_content"` + - `"in_progress"` - The type of the input item. Always `encrypted_content`. + - `"completed"` - - `"encrypted_content"` + - `"incomplete"` - - `recipient: string` + - `ShellCallOutput object { call_id, output, type, 5 more }` - The destination agent identity. + The streamed output items emitted by a shell tool call. - - `type: "agent_message"` + - `call_id: string` - The item type. Always `agent_message`. + The unique ID of the shell tool call generated by the model. - - `"agent_message"` + - `output: array of BetaResponseFunctionShellCallOutputContent` - - `id: optional string` + Captured chunks of stdout and stderr output, along with their associated outcomes. - The unique ID of this agent message item. + - `outcome: object { type } or object { exit_code, type }` - - `agent: optional object { agent_name }` + The exit or timeout outcome associated with this shell call. - The agent that produced this item. + - `Timeout object { type }` - - `agent_name: string` + Indicates that the shell call exceeded its configured time limit. - The canonical name of the agent that produced this item. + - `type: "timeout"` - - `MultiAgentCall object { action, arguments, call_id, 3 more }` + The outcome type. Always `timeout`. - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `"timeout"` - The multi-agent action that was executed. + - `Exit object { exit_code, type }` - - `"spawn_agent"` + Indicates that the shell commands finished and returned an exit code. - - `"interrupt_agent"` + - `exit_code: number` - - `"list_agents"` + The exit code returned by the shell process. - - `"send_message"` + - `type: "exit"` - - `"followup_task"` + The outcome type. Always `exit`. - - `"wait_agent"` + - `"exit"` - - `arguments: string` + - `stderr: string` - The action arguments as a JSON string. + Captured stderr output for the shell call. - - `call_id: string` + - `stdout: string` - The unique ID linking this call to its output. + Captured stdout output for the shell call. - - `type: "multi_agent_call"` + - `type: "shell_call_output"` - The item type. Always `multi_agent_call`. + The type of the item. Always `shell_call_output`. - - `"multi_agent_call"` + - `"shell_call_output"` - `id: optional string` - The unique ID of this multi-agent call. + The unique ID of the shell tool call output. Populated when this item is returned via API. - `agent: optional object { agent_name }` @@ -183762,127 +184031,123 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `MultiAgentCallOutput object { action, call_id, output, 3 more }` - - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - The multi-agent action that produced this result. + - `caller: optional object { type } or object { caller_id, type }` - - `"spawn_agent"` + The execution context that produced this tool call. - - `"interrupt_agent"` + - `Direct object { type }` - - `"list_agents"` + - `type: "direct"` - - `"send_message"` + The caller type. Always `direct`. - - `"followup_task"` + - `"direct"` - - `"wait_agent"` + - `Program object { caller_id, type }` - - `call_id: string` + - `caller_id: string` - The unique ID of the multi-agent call. + The call ID of the program item that produced this tool call. - - `output: array of object { text, type, annotations }` + - `type: "program"` - Text output returned by the multi-agent action. + The caller type. Always `program`. - - `text: string` + - `"program"` - The text content. + - `max_output_length: optional number` - - `type: "output_text"` + The maximum number of UTF-8 characters captured for this shell call's combined output. - The content type. Always `output_text`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"output_text"` + The status of the shell call output. - - `annotations: optional 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 }` + - `"in_progress"` - Citations associated with the text content. + - `"completed"` - - `FileCitation object { file_id, filename, index, type }` + - `"incomplete"` - - `file_id: string` + - `ApplyPatchCall object { call_id, operation, status, 4 more }` - The ID of the file. + A tool call representing a request to create, delete, or update files using diff patches. - - `filename: string` + - `call_id: string` - The filename of the file cited. + The unique ID of the apply patch tool call generated by the model. - - `index: number` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - The index of the file in the list of files. + The specific create, delete, or update instruction for the apply_patch tool call. - - `type: "file_citation"` + - `CreateFile object { diff, path, type }` - The citation type. Always `file_citation`. + Instruction for creating a new file via the apply_patch tool. - - `"file_citation"` + - `diff: string` - - `URLCitation object { end_index, start_index, title, 2 more }` + Unified diff content to apply when creating the file. - - `end_index: number` + - `path: string` - The index of the last character of the citation in the message. + Path of the file to create relative to the workspace root. - - `start_index: number` + - `type: "create_file"` - The index of the first character of the citation in the message. + The operation type. Always `create_file`. - - `title: string` + - `"create_file"` - The title of the cited resource. + - `DeleteFile object { path, type }` - - `type: "url_citation"` + Instruction for deleting an existing file via the apply_patch tool. - The citation type. Always `url_citation`. + - `path: string` - - `"url_citation"` + Path of the file to delete relative to the workspace root. - - `url: string` + - `type: "delete_file"` - The URL of the cited resource. + The operation type. Always `delete_file`. - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + - `"delete_file"` - - `container_id: string` + - `UpdateFile object { diff, path, type }` - The ID of the container. + Instruction for updating an existing file via the apply_patch tool. - - `end_index: number` + - `diff: string` - The index of the last character of the citation in the message. + Unified diff content to apply to the existing file. - - `file_id: string` + - `path: string` - The ID of the container file. + Path of the file to update relative to the workspace root. - - `filename: string` + - `type: "update_file"` - The filename of the container file cited. + The operation type. Always `update_file`. - - `start_index: number` + - `"update_file"` - The index of the first character of the citation in the message. + - `status: "in_progress" or "completed"` - - `type: "container_file_citation"` + The status of the apply patch tool call. One of `in_progress` or `completed`. - The citation type. Always `container_file_citation`. + - `"in_progress"` - - `"container_file_citation"` + - `"completed"` - - `type: "multi_agent_call_output"` + - `type: "apply_patch_call"` - The item type. Always `multi_agent_call_output`. + The type of the item. Always `apply_patch_call`. - - `"multi_agent_call_output"` + - `"apply_patch_call"` - `id: optional string` - The unique ID of this multi-agent call output. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - `agent: optional object { agent_name }` @@ -183892,1248 +184157,1305 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `ToolSearchCall object { arguments, type, id, 4 more }` + - `caller: optional object { type } or object { caller_id, type }` - - `arguments: unknown` + The execution context that produced this tool call. - The arguments supplied to the tool search call. + - `Direct object { type }` - - `type: "tool_search_call"` + - `type: "direct"` - The item type. Always `tool_search_call`. + The caller type. Always `direct`. - - `"tool_search_call"` + - `"direct"` - - `id: optional string` + - `Program object { caller_id, type }` - The unique ID of this tool search call. + - `caller_id: string` - - `agent: optional object { agent_name }` + The call ID of the program item that produced this tool call. - The agent that produced this item. + - `type: "program"` - - `agent_name: string` + The caller type. Always `program`. - The canonical name of the agent that produced this item. + - `"program"` - - `call_id: optional string` + - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` - The unique ID of the tool search call generated by the model. + The streamed output emitted by an apply patch tool call. - - `execution: optional "server" or "client"` + - `call_id: string` - Whether tool search was executed by the server or by the client. + The unique ID of the apply patch tool call generated by the model. - - `"server"` + - `status: "completed" or "failed"` - - `"client"` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"completed"` - The status of the tool search call. + - `"failed"` - - `"in_progress"` + - `type: "apply_patch_call_output"` - - `"completed"` + The type of the item. Always `apply_patch_call_output`. - - `"incomplete"` + - `"apply_patch_call_output"` - - `ToolSearchOutput object { tools, type, id, 4 more }` + - `id: optional string` - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - The loaded tool definitions returned by the tool search output. + - `agent: optional object { agent_name }` - - `Function object { name, parameters, strict, 5 more }` + The agent that produced this item. - 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). + - `agent_name: string` - - `name: string` + The canonical name of the agent that produced this item. - The name of the function to call. + - `caller: optional object { type } or object { caller_id, type }` - - `parameters: map[unknown]` + The execution context that produced this tool call. - A JSON schema object describing the parameters of the function. + - `Direct object { type }` - - `strict: boolean` + - `type: "direct"` - Whether strict parameter validation is enforced for this function tool. + The caller type. Always `direct`. - - `type: "function"` + - `"direct"` - The type of the function tool. Always `function`. + - `Program object { caller_id, type }` - - `"function"` + - `caller_id: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The call ID of the program item that produced this tool call. - The tool invocation context(s). + - `type: "program"` - - `"direct"` + The caller type. Always `program`. - - `"programmatic"` + - `"program"` - - `defer_loading: optional boolean` + - `output: optional string` - Whether this function is deferred and loaded via tool search. + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - `description: optional string` + - `McpListTools object { id, server_label, tools, 3 more }` - A description of the function. Used by the model to determine whether or not to call the function. + A list of tools available on an MCP server. - - `output_schema: optional map[unknown]` + - `id: string` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The unique ID of the list. - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `server_label: 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 label of the MCP server. - - `type: "file_search"` + - `tools: array of object { input_schema, name, annotations, description }` - The type of the file search tool. Always `file_search`. + The tools available on the server. - - `"file_search"` + - `input_schema: unknown` - - `vector_store_ids: array of string` + The JSON schema describing the tool's input. - The IDs of the vector stores to search. + - `name: string` - - `filters: optional object { key, type, value } or object { filters, type }` + The name of the tool. - A filter to apply. + - `annotations: optional unknown` - - `ComparisonFilter object { key, type, value }` + Additional annotations about the tool. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `description: optional string` - - `key: string` + The description of the tool. - The key to compare against the value. + - `type: "mcp_list_tools"` - - `type: "eq" or "ne" or "gt" or 5 more` + The type of the item. Always `mcp_list_tools`. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"mcp_list_tools"` - - `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 + - `agent: optional object { agent_name }` - - `"eq"` + The agent that produced this item. - - `"ne"` + - `agent_name: string` - - `"gt"` + The canonical name of the agent that produced this item. - - `"gte"` + - `error: optional string` - - `"lt"` + Error message if the server could not list tools. - - `"lte"` + - `McpApprovalRequest object { id, arguments, name, 3 more }` - - `"in"` + A request for human approval of a tool invocation. - - `"nin"` + - `id: string` - - `value: string or number or boolean or array of string or number` + The unique ID of the approval request. - The value to compare against the attribute key; supports string, number, or boolean types. + - `arguments: string` - - `string` + A JSON string of arguments for the tool. - - `number` + - `name: string` - - `boolean` + The name of the tool to run. - - `array of string or number` + - `server_label: string` - - `string` + The label of the MCP server making the request. - - `number` + - `type: "mcp_approval_request"` - - `CompoundFilter object { filters, type }` + The type of the item. Always `mcp_approval_request`. - Combine multiple filters using `and` or `or`. + - `"mcp_approval_request"` - - `filters: array of object { key, type, value } or unknown` + - `agent: optional object { agent_name }` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + The agent that produced this item. - - `ComparisonFilter object { key, type, value }` + - `agent_name: string` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The canonical name of the agent that produced this item. - - `key: string` + - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` - The key to compare against the value. + A response to an MCP approval request. - - `type: "eq" or "ne" or "gt" or 5 more` + - `approval_request_id: string` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The ID of the approval request being answered. - - `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 + - `approve: boolean` - - `"eq"` + Whether the request was approved. - - `"ne"` + - `type: "mcp_approval_response"` - - `"gt"` + The type of the item. Always `mcp_approval_response`. - - `"gte"` + - `"mcp_approval_response"` - - `"lt"` + - `id: optional string` - - `"lte"` + The unique ID of the approval response - - `"in"` + - `agent: optional object { agent_name }` - - `"nin"` + The agent that produced this item. - - `value: string or number or boolean or array of string or number` + - `agent_name: string` - The value to compare against the attribute key; supports string, number, or boolean types. + The canonical name of the agent that produced this item. - - `string` + - `reason: optional string` - - `number` + Optional reason for the decision. - - `boolean` + - `McpCall object { id, arguments, name, 7 more }` - - `array of string or number` + An invocation of a tool on an MCP server. - - `string` + - `id: string` - - `number` + The unique ID of the tool call. - - `unknown` + - `arguments: string` - - `type: "and" or "or"` + A JSON string of the arguments passed to the tool. - Type of operation: `and` or `or`. + - `name: string` - - `"and"` + The name of the tool that was run. - - `"or"` + - `server_label: string` - - `max_num_results: optional number` + The label of the MCP server running the tool. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `type: "mcp_call"` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + The type of the item. Always `mcp_call`. - Ranking options for search. + - `"mcp_call"` - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `agent: optional object { agent_name }` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + The agent that produced this item. - - `embedding_weight: number` + - `agent_name: string` - The weight of the embedding in the reciprocal ranking fusion. + The canonical name of the agent that produced this item. - - `text_weight: number` + - `approval_request_id: optional string` - The weight of the text in the reciprocal ranking fusion. + 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. - - `ranker: optional "auto" or "default-2024-11-15"` + - `error: optional string` - The ranker to use for the file search. + The error from the tool call, if any. - - `"auto"` + - `output: optional string` - - `"default-2024-11-15"` + The output from the tool call. - - `score_threshold: optional number` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `Computer object { type }` + - `"in_progress"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `"completed"` - - `type: "computer"` + - `"incomplete"` - The type of the computer tool. Always `computer`. + - `"calling"` - - `"computer"` + - `"failed"` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `CustomToolCallOutput object { call_id, output, type, 3 more }` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The output of a custom tool call from your code, being sent back to the model. - - `display_height: number` + - `call_id: string` - The height of the computer display. + The call ID, used to map this custom tool call output to a custom tool call. - - `display_width: number` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The width of the computer display. + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `environment: "windows" or "mac" or "linux" or 2 more` + - `StringOutput = string` - The type of computer environment to control. + A string of the output of the custom tool call. - - `"windows"` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `"mac"` + Text, image, or file output of the custom tool call. - - `"linux"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `"ubuntu"` + A text input to the model. - - `"browser"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `type: "computer_use_preview"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - The type of the computer use tool. Always `computer_use_preview`. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `"computer_use_preview"` + A file input to the model. - - `WebSearch object { type, filters, search_context_size, user_location }` + - `type: "custom_tool_call_output"` - 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 custom tool call output. Always `custom_tool_call_output`. - - `type: "web_search" or "web_search_2025_08_26"` + - `"custom_tool_call_output"` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `id: optional string` - - `"web_search"` + The unique ID of the custom tool call output in the OpenAI platform. - - `"web_search_2025_08_26"` + - `agent: optional object { agent_name }` - - `filters: optional object { allowed_domains }` + The agent that produced this item. - Filters for the search. + - `agent_name: string` - - `allowed_domains: optional array of string` + The canonical name of the agent that produced this item. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `caller: optional object { type } or object { caller_id, type }` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The execution context that produced this tool call. - - `search_context_size: optional "low" or "medium" or "high"` + - `Direct object { 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: "direct"` - - `"low"` + The caller type. Always `direct`. - - `"medium"` + - `"direct"` - - `"high"` + - `Program object { caller_id, type }` - - `user_location: optional object { city, country, region, 2 more }` + - `caller_id: string` - The approximate location of the user. + The call ID of the program item that produced this tool call. - - `city: optional string` + - `type: "program"` - Free text input for the city of the user, e.g. `San Francisco`. + The caller type. Always `program`. - - `country: optional string` + - `"program"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `CustomToolCall object { call_id, input, name, 5 more }` - - `region: optional string` + A call to a custom tool created by the model. - Free text input for the region of the user, e.g. `California`. + - `call_id: string` - - `timezone: optional string` + An identifier used to map this custom tool call to a tool call output. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `input: string` - - `type: optional "approximate"` + The input for the custom tool call generated by the model. - The type of location approximation. Always `approximate`. + - `name: string` - - `"approximate"` + The name of the custom tool being called. - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `type: "custom_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). + The type of the custom tool call. Always `custom_tool_call`. - - `server_label: string` + - `"custom_tool_call"` - A label for this MCP server, used to identify it in tool calls. + - `id: optional string` - - `type: "mcp"` + The unique ID of the custom tool call in the OpenAI platform. - The type of the MCP tool. Always `mcp`. + - `agent: optional object { agent_name }` - - `"mcp"` + The agent that produced this item. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `agent_name: string` - The tool invocation context(s). + The canonical name of the agent that produced this item. - - `"direct"` + - `caller: optional object { type } or object { caller_id, type }` - - `"programmatic"` + The execution context that produced this tool call. - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `Direct object { type }` - List of allowed tool names or a filter object. + - `type: "direct"` - - `McpAllowedTools = array of string` + - `"direct"` - A string array of allowed tool names + - `Program object { caller_id, type }` - - `McpToolFilter object { read_only, tool_names }` + - `caller_id: string` - A filter object to specify which tools are allowed. + The call ID of the program item that produced this tool call. - - `read_only: optional boolean` + - `type: "program"` - 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. + - `"program"` - - `tool_names: optional array of string` + - `namespace: optional string` - List of allowed tool names. + The namespace of the custom tool being called. - - `authorization: optional string` + - `CompactionTrigger object { type, agent }` - 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. + Compacts the current context. Must be the final input item. - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `type: "compaction_trigger"` - 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 type of the item. Always `compaction_trigger`. - Currently supported `connector_id` values are: + - `"compaction_trigger"` - - 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` + - `agent: optional object { agent_name }` - - `"connector_dropbox"` + The agent that produced this item. - - `"connector_gmail"` + - `agent_name: string` - - `"connector_googlecalendar"` + The canonical name of the agent that produced this item. - - `"connector_googledrive"` + - `ItemReference object { id, agent, type }` - - `"connector_microsoftteams"` + An internal identifier for an item to reference. - - `"connector_outlookcalendar"` + - `id: string` - - `"connector_outlookemail"` + The ID of the item to reference. - - `"connector_sharepoint"` + - `agent: optional object { agent_name }` - - `defer_loading: optional boolean` + The agent that produced this item. - Whether this MCP tool is deferred and discovered via tool search. + - `agent_name: string` - - `headers: optional map[string]` + The canonical name of the agent that produced this item. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `type: optional "item_reference"` - - `require_approval: optional object { always, never } or "always" or "never"` + The type of item to reference. Always `item_reference`. - Specify which of the MCP server's tools require approval. + - `"item_reference"` - - `McpToolApprovalFilter object { always, never }` + - `Program object { id, call_id, code, 3 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 this program item. - A filter object to specify which tools are allowed. + - `call_id: string` - - `read_only: optional boolean` + The stable call ID of the program item. - 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. + - `code: string` - - `tool_names: optional array of string` + The JavaScript source executed by programmatic tool calling. - List of allowed tool names. + - `fingerprint: string` - - `never: optional object { read_only, tool_names }` + Opaque program replay fingerprint that must be round-tripped. - A filter object to specify which tools are allowed. + - `type: "program"` - - `read_only: optional boolean` + The item type. Always `program`. - 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. + - `"program"` - - `tool_names: optional array of string` + - `agent: optional object { agent_name }` - List of allowed tool names. + The agent that produced this item. - - `McpToolApprovalSetting = "always" or "never"` + - `agent_name: 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. + The canonical name of the agent that produced this item. - - `"always"` + - `ProgramOutput object { id, call_id, result, 3 more }` - - `"never"` + - `id: string` - - `server_description: optional string` + The unique ID of this program output item. - Optional description of the MCP server, used to provide more context. + - `call_id: string` - - `server_url: optional string` + The call ID of the program item. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `result: string` - - `tunnel_id: optional string` + The result produced by the program item. - 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. + - `status: "completed" or "incomplete"` - - `CodeInterpreter object { container, type, allowed_callers }` + The terminal status of the program output. - A tool that runs Python code to help generate a response to a prompt. + - `"completed"` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `"incomplete"` - 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: "program_output"` - - `string` + The item type. Always `program_output`. - The container ID. + - `"program_output"` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `agent: optional object { agent_name }` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + The agent that produced this item. - - `type: "auto"` + - `agent_name: string` - Always `auto`. + The canonical name of the agent that produced this item. - - `"auto"` + - `instructions: optional string` - - `file_ids: optional array of string` + A system (or developer) message inserted into the model's context. - An optional list of uploaded files to make available to your code. + 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. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `max_output_tokens: optional number` - The memory limit for the code interpreter container. + 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). - - `"1g"` + - `max_tool_calls: optional number` - - `"4g"` + 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. - - `"16g"` + - `metadata: optional map[string]` - - `"64g"` + 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. - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - Network access policy for the container. + - `model: optional "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - - `BetaContainerNetworkPolicyDisabled object { type }` + 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: "disabled"` + - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` - Disable outbound network access. Always `disabled`. + 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. - - `"disabled"` + - `"gpt-5.6-sol"` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `"gpt-5.6-terra"` - - `allowed_domains: array of string` + - `"gpt-5.6-luna"` - A list of allowed domains when type is `allowlist`. + - `"gpt-5.4"` - - `type: "allowlist"` + - `"gpt-5.4-mini"` - Allow outbound network access only to specified domains. Always `allowlist`. + - `"gpt-5.4-nano"` - - `"allowlist"` + - `"gpt-5.4-mini-2026-03-17"` - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + - `"gpt-5.4-nano-2026-03-17"` - Optional domain-scoped secrets for allowlisted domains. + - `"gpt-5.3-chat-latest"` - - `domain: string` + - `"gpt-5.2"` - The domain associated with the secret. + - `"gpt-5.2-2025-12-11"` - - `name: string` + - `"gpt-5.2-chat-latest"` - The name of the secret to inject for the domain. + - `"gpt-5.2-pro"` - - `value: string` + - `"gpt-5.2-pro-2025-12-11"` - The secret value to inject for the domain. + - `"gpt-5.1"` - - `type: "code_interpreter"` + - `"gpt-5.1-2025-11-13"` - The type of the code interpreter tool. Always `code_interpreter`. + - `"gpt-5.1-codex"` - - `"code_interpreter"` + - `"gpt-5.1-mini"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"gpt-5.1-chat-latest"` - The tool invocation context(s). + - `"gpt-5"` - - `"direct"` + - `"gpt-5-mini"` - - `"programmatic"` + - `"gpt-5-nano"` - - `ProgrammaticToolCalling object { type }` + - `"gpt-5-2025-08-07"` - - `type: "programmatic_tool_calling"` + - `"gpt-5-mini-2025-08-07"` - The type of the tool. Always `programmatic_tool_calling`. + - `"gpt-5-nano-2025-08-07"` - - `"programmatic_tool_calling"` + - `"gpt-5-chat-latest"` - - `ImageGeneration object { type, action, background, 9 more }` + - `"gpt-4.1"` - A tool that generates images using the GPT image models. + - `"gpt-4.1-mini"` - - `type: "image_generation"` + - `"gpt-4.1-nano"` - The type of the image generation tool. Always `image_generation`. + - `"gpt-4.1-2025-04-14"` - - `"image_generation"` + - `"gpt-4.1-mini-2025-04-14"` - - `action: optional "generate" or "edit" or "auto"` + - `"gpt-4.1-nano-2025-04-14"` - Whether to generate a new image or edit an existing image. Default: `auto`. + - `"o4-mini"` - - `"generate"` + - `"o4-mini-2025-04-16"` - - `"edit"` + - `"o3"` - - `"auto"` + - `"o3-2025-04-16"` - - `background: optional "transparent" or "opaque" or "auto"` + - `"o3-mini"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + - `"o3-mini-2025-01-31"` - - `"transparent"` + - `"o1"` - - `"opaque"` + - `"o1-2024-12-17"` - - `"auto"` + - `"o1-preview"` - - `input_fidelity: optional "high" or "low"` + - `"o1-preview-2024-09-12"` - 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`. + - `"o1-mini"` - - `"high"` + - `"o1-mini-2024-09-12"` - - `"low"` + - `"gpt-4o"` - - `input_image_mask: optional object { file_id, image_url }` + - `"gpt-4o-2024-11-20"` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `"gpt-4o-2024-08-06"` - - `file_id: optional string` + - `"gpt-4o-2024-05-13"` - File ID for the mask image. + - `"gpt-4o-audio-preview"` - - `image_url: optional string` + - `"gpt-4o-audio-preview-2024-10-01"` - Base64-encoded mask image. + - `"gpt-4o-audio-preview-2024-12-17"` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"gpt-4o-audio-preview-2025-06-03"` - The image generation model to use. Default: `gpt-image-1`. + - `"gpt-4o-mini-audio-preview"` - - `string` + - `"gpt-4o-mini-audio-preview-2024-12-17"` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"gpt-4o-search-preview"` - The image generation model to use. Default: `gpt-image-1`. + - `"gpt-4o-mini-search-preview"` - - `"gpt-image-1"` + - `"gpt-4o-search-preview-2025-03-11"` - - `"gpt-image-1-mini"` + - `"gpt-4o-mini-search-preview-2025-03-11"` - - `"gpt-image-1.5"` + - `"chatgpt-4o-latest"` - - `moderation: optional "auto" or "low"` + - `"codex-mini-latest"` - Moderation level for the generated image. Default: `auto`. + - `"gpt-4o-mini"` - - `"auto"` + - `"gpt-4o-mini-2024-07-18"` - - `"low"` + - `"gpt-4-turbo"` - - `output_compression: optional number` + - `"gpt-4-turbo-2024-04-09"` - Compression level for the output image. Default: 100. + - `"gpt-4-0125-preview"` - - `output_format: optional "png" or "webp" or "jpeg"` + - `"gpt-4-turbo-preview"` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `"gpt-4-1106-preview"` - - `"png"` + - `"gpt-4-vision-preview"` - - `"webp"` + - `"gpt-4"` - - `"jpeg"` + - `"gpt-4-0314"` - - `partial_images: optional number` + - `"gpt-4-0613"` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `"gpt-4-32k"` - - `quality: optional "low" or "medium" or "high" or "auto"` + - `"gpt-4-32k-0314"` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `"gpt-4-32k-0613"` - - `"low"` + - `"gpt-3.5-turbo"` - - `"medium"` + - `"gpt-3.5-turbo-16k"` - - `"high"` + - `"gpt-3.5-turbo-0301"` - - `"auto"` + - `"gpt-3.5-turbo-0613"` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `"gpt-3.5-turbo-1106"` - 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`. + - `"gpt-3.5-turbo-0125"` - - `string` + - `"gpt-3.5-turbo-16k-0613"` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `"o1-pro"` - 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`. + - `"o1-pro-2025-03-19"` - - `"1024x1024"` + - `"o3-pro"` - - `"1024x1536"` + - `"o3-pro-2025-06-10"` - - `"1536x1024"` + - `"o3-deep-research"` - - `"auto"` + - `"o3-deep-research-2025-06-26"` - - `LocalShell object { type }` + - `"o4-mini-deep-research"` - A tool that allows the model to execute shell commands in a local environment. + - `"o4-mini-deep-research-2025-06-26"` - - `type: "local_shell"` + - `"computer-use-preview"` - The type of the local shell tool. Always `local_shell`. + - `"computer-use-preview-2025-03-11"` - - `"local_shell"` + - `"gpt-5-codex"` - - `Shell object { type, allowed_callers, environment }` + - `"gpt-5-pro"` - A tool that allows the model to execute shell commands. + - `"gpt-5-pro-2025-10-06"` - - `type: "shell"` + - `"gpt-5.1-codex-max"` - The type of the shell tool. Always `shell`. + - `string` - - `"shell"` + - `moderation: optional object { model, policy }` - - `allowed_callers: optional array of "direct" or "programmatic"` + Configuration for running moderation on the input and output of this response. - The tool invocation context(s). + - `model: string` - - `"direct"` + The moderation model to use for moderated completions, e.g. 'omni-moderation-latest'. - - `"programmatic"` + - `policy: optional object { input, output }` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + The policy to apply to moderated response input and output. - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `input: optional object { mode }` - - `type: "container_auto"` + The moderation policy for the response input. - Automatically creates a container for this request + - `mode: "score" or "block"` - - `"container_auto"` + - `"score"` - - `file_ids: optional array of string` + - `"block"` - An optional list of uploaded files to make available to your code. + - `output: optional object { mode }` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + The moderation policy for the response output. - The memory limit for the container. + - `mode: "score" or "block"` - - `"1g"` + - `"score"` - - `"4g"` + - `"block"` - - `"16g"` + - `multi_agent: optional object { enabled, max_concurrent_subagents }` - - `"64g"` + Configuration for server-hosted multi-agent execution. - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `enabled: boolean` - Network access policy for the container. + Whether to enable server-hosted multi-agent execution for this response. - - `BetaContainerNetworkPolicyDisabled object { type }` + - `max_concurrent_subagents: optional number` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + `max_concurrent_subagents` sets the maximum number of subagents that can be active simultaneously across the entire agent tree. It includes all descendants—children, grandchildren, and deeper subagents—but excludes the root agent. + The API does not impose a fixed upper bound on this setting. The default is `3`, which is recommended for most workloads. Multi-agent runs also have no fixed limit on tree depth or the total number of subagents created during a run. - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + - `parallel_tool_calls: optional boolean` - An optional list of skills referenced by id or inline data. + Whether to allow the model to run tool calls in parallel. - - `BetaSkillReference object { skill_id, type, version }` + - `previous_response_id: optional string` - - `skill_id: 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`. - The ID of the referenced skill. + - `prompt: optional BetaResponsePrompt` - - `type: "skill_reference"` + Reference to a prompt template and its variables. + [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). - References a skill created with the /v1/skills endpoint. + - `id: string` - - `"skill_reference"` + The unique identifier of the prompt template to use. - - `version: optional string` + - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + 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. - - `BetaInlineSkill object { description, name, source, type }` + - `string` - - `description: string` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - The description of the skill. + A text input to the model. - - `name: string` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - The name of the skill. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `source: BetaInlineSkillSource` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - Inline skill payload + A file input to the model. - - `data: string` + - `version: optional string` - Base64-encoded skill zip bundle. + Optional version of the prompt template. - - `media_type: "application/zip"` + - `prompt_cache_key: optional string` - The media type of the inline skill payload. Must be `application/zip`. + 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). - - `"application/zip"` + - `prompt_cache_options: optional object { mode, ttl }` - - `type: "base64"` + 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 type of the inline skill source. Must be `base64`. + - `mode: optional "implicit" or "explicit"` - - `"base64"` + 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. - - `type: "inline"` + - `"implicit"` - Defines an inline skill for this request. + - `"explicit"` - - `"inline"` + - `ttl: optional "30m"` - - `BetaLocalEnvironment object { type, skills }` + 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: "local"` + - `"30m"` - Use a local computer environment. + - `prompt_cache_retention: optional "in_memory" or "24h"` - - `"local"` + Deprecated. Use `prompt_cache_options.ttl` instead. - - `skills: optional array of BetaLocalSkill` + 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. - An optional list of skills. + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - - `description: string` + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - The description of the skill. + - `"in_memory"` - - `name: string` + - `"24h"` - The name of the skill. + - `reasoning: optional object { context, effort, generate_summary, 2 more }` - - `path: string` + **gpt-5 and o-series models only** - The path to the directory containing the skill. + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `BetaContainerReference object { container_id, type }` + - `context: optional "auto" or "current_turn" or "all_turns"` - - `container_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`. - The ID of the referenced container. + When returned on a response, this is the effective reasoning context mode + used for the response. - - `type: "container_reference"` + - `"auto"` - References a container created with the /v1/containers endpoint + - `"current_turn"` - - `"container_reference"` + - `"all_turns"` - - `Custom object { name, type, allowed_callers, 3 more }` + - `effort: optional "none" or "minimal" or "low" or 4 more` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + 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. - - `name: string` + - `"none"` - The name of the custom tool, used to identify it in tool calls. + - `"minimal"` - - `type: "custom"` + - `"low"` - The type of the custom tool. Always `custom`. + - `"medium"` - - `"custom"` + - `"high"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"xhigh"` - The tool invocation context(s). + - `"max"` - - `"direct"` + - `generate_summary: optional "auto" or "concise" or "detailed"` - - `"programmatic"` + **Deprecated:** use `summary` instead. - - `defer_loading: optional boolean` + 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`. - Whether this tool should be deferred and discovered via tool search. + - `"auto"` - - `description: optional string` + - `"concise"` - Optional description of the custom tool, used to provide more context. + - `"detailed"` - - `format: optional object { type } or object { definition, syntax, type }` + - `mode: optional string or "standard" or "pro"` - The input format for the custom tool. Default is unconstrained text. + Controls the reasoning execution mode for the request. - - `Text object { type }` + When returned on a response, this is the effective execution mode. - Unconstrained free-form text. + - `string` - - `type: "text"` + - `"standard" or "pro"` - Unconstrained text format. Always `text`. + Controls the reasoning execution mode for the request. - - `"text"` + When returned on a response, this is the effective execution mode. - - `Grammar object { definition, syntax, type }` + - `"standard"` - A grammar defined by the user. + - `"pro"` - - `definition: string` + - `summary: optional "auto" or "concise" or "detailed"` - The grammar definition. + 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`. - - `syntax: "lark" or "regex"` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - The syntax of the grammar definition. One of `lark` or `regex`. + - `"auto"` - - `"lark"` + - `"concise"` - - `"regex"` + - `"detailed"` - - `type: "grammar"` + - `safety_identifier: optional string` - Grammar format. Always `grammar`. + 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). - - `"grammar"` + - `service_tier: optional "auto" or "default" or "flex" or 2 more` - - `Namespace object { description, name, tools, type }` + Specifies the processing type used for serving the request. - Groups function/custom tools under a shared namespace. + - 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'. - - `description: 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. - A description of the namespace shown to the model. + - `"auto"` - - `name: string` + - `"default"` - The namespace name used in tool calls (for example, `crm`). + - `"flex"` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `"scale"` - The function/custom tools available inside this namespace. + - `"priority"` - - `Function object { name, type, allowed_callers, 5 more }` + - `store: optional boolean` - - `name: string` + Whether to store the generated model response for later retrieval via + API. - - `type: "function"` + - `stream: optional boolean` - - `"function"` + 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. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `stream_options: optional object { include_obfuscation }` - The tool invocation context(s). + Options for streaming responses. Only set this when you set `stream: true`. - - `"direct"` + - `include_obfuscation: optional boolean` - - `"programmatic"` + 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. - - `defer_loading: optional boolean` + - `temperature: optional number` - Whether this function should be deferred and discovered via tool search. + 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. - - `description: optional string` + - `text: optional BetaResponseTextConfig` - - `output_schema: optional map[unknown]` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - [Text inputs and outputs](/docs/guides/text) + - [Structured Outputs](/docs/guides/structured-outputs) - - `parameters: optional unknown` + - `format: optional BetaResponseFormatTextConfig` - - `strict: optional boolean` + An object specifying the format that the model must output. - 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. + 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). - - `Custom object { name, type, allowed_callers, 3 more }` + The default format is `{ "type": "text" }` with no additional options. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + **Not recommended for gpt-4o and newer models:** - - `name: 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 name of the custom tool, used to identify it in tool calls. + - `Text object { type }` - - `type: "custom"` + Default response format. Used to generate text responses. - The type of the custom tool. Always `custom`. + - `type: "text"` - - `"custom"` + The type of response format being defined. Always `text`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"text"` - The tool invocation context(s). + - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` - - `"direct"` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `"programmatic"` + - `name: string` - - `defer_loading: optional boolean` + 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. - Whether this tool should be deferred and discovered via tool search. + - `schema: map[unknown]` - - `description: optional string` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - Optional description of the custom tool, used to provide more context. + - `type: "json_schema"` - - `format: optional object { type } or object { definition, syntax, type }` + The type of response format being defined. Always `json_schema`. - The input format for the custom tool. Default is unconstrained text. + - `"json_schema"` - - `Text object { type }` + - `description: optional string` - Unconstrained free-form text. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `type: "text"` + - `strict: optional boolean` - Unconstrained text format. Always `text`. + 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). - - `"text"` + - `JSONObject object { type }` - - `Grammar object { definition, syntax, 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. - A grammar defined by the user. + - `type: "json_object"` - - `definition: string` + The type of response format being defined. Always `json_object`. - The grammar definition. + - `"json_object"` - - `syntax: "lark" or "regex"` + - `verbosity: optional "low" or "medium" or "high"` - The syntax of the grammar definition. One of `lark` or `regex`. + 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`. - - `"lark"` + - `"low"` - - `"regex"` + - `"medium"` - - `type: "grammar"` + - `"high"` - Grammar format. Always `grammar`. + - `tool_choice: optional BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - - `"grammar"` + 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. - - `type: "namespace"` + - `BetaToolChoiceOptions = "none" or "auto" or "required"` - The type of the tool. Always `namespace`. + Controls which (if any) tool is called by the model. - - `"namespace"` + `none` means the model will not call any tool and instead generates a message. - - `ToolSearch object { type, description, execution, parameters }` + `auto` means the model can pick between generating a message or calling one or + more tools. - Hosted or BYOT tool search configuration for deferred tools. + `required` means the model must call one or more tools. - - `type: "tool_search"` + - `"none"` - The type of the tool. Always `tool_search`. + - `"auto"` - - `"tool_search"` + - `"required"` - - `description: optional string` + - `BetaToolChoiceAllowed object { mode, tools, type }` - Description shown to the model for a client-executed tool search tool. + Constrains the tools available to the model to a pre-defined set. - - `execution: optional "server" or "client"` + - `mode: "auto" or "required"` - Whether tool search is executed by the server or by the client. + Constrains the tools available to the model to a pre-defined set. - - `"server"` + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `"client"` + `required` requires the model to call one or more of the allowed tools. - - `parameters: optional unknown` + - `"auto"` - Parameter schema for a client-executed tool search tool. + - `"required"` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `tools: array of map[unknown]` - 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 list of tool definitions that the model should be allowed to call. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + For the Responses API, the list of tool definitions might look like: - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `"web_search_preview"` + - `type: "allowed_tools"` - - `"web_search_preview_2025_03_11"` + Allowed tool configuration type. Always `allowed_tools`. - - `search_content_types: optional array of "text" or "image"` + - `"allowed_tools"` - - `"text"` + - `BetaToolChoiceTypes object { type }` - - `"image"` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](/docs/guides/tools). - - `search_context_size: optional "low" or "medium" or "high"` + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The type of hosted tool the model should to use. Learn more about + [built-in tools](/docs/guides/tools). - - `"low"` + Allowed values are: - - `"medium"` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - - `"high"` + - `"file_search"` - - `user_location: optional object { type, city, country, 2 more }` + - `"web_search_preview"` - The user's location. + - `"computer"` - - `type: "approximate"` + - `"computer_use_preview"` - The type of location approximation. Always `approximate`. + - `"computer_use"` - - `"approximate"` + - `"web_search_preview_2025_03_11"` - - `city: optional string` + - `"image_generation"` - Free text input for the city of the user, e.g. `San Francisco`. + - `"code_interpreter"` - - `country: optional string` + - `BetaToolChoiceFunction object { name, type }` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + Use this option to force the model to call a specific function. - - `region: optional string` + - `name: string` - Free text input for the region of the user, e.g. `California`. + The name of the function to call. - - `timezone: optional string` + - `type: "function"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + For function calling, the type is always `function`. - - `ApplyPatch object { type, allowed_callers }` + - `"function"` - Allows the assistant to create, delete, or update files using unified diffs. + - `BetaToolChoiceMcp object { server_label, type, name }` - - `type: "apply_patch"` + Use this option to force the model to call a specific tool on a remote MCP server. - The type of the tool. Always `apply_patch`. + - `server_label: string` - - `"apply_patch"` + The label of the MCP server to use. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: "mcp"` - The tool invocation context(s). + For MCP tools, the type is always `mcp`. - - `"direct"` + - `"mcp"` - - `"programmatic"` + - `name: optional string` - - `type: "tool_search_output"` + The name of the tool to call on the server. - The item type. Always `tool_search_output`. + - `BetaToolChoiceCustom object { name, type }` - - `"tool_search_output"` + Use this option to force the model to call a specific custom tool. - - `id: optional string` + - `name: string` - The unique ID of this tool search output. + The name of the custom tool to call. - - `agent: optional object { agent_name }` + - `type: "custom"` - The agent that produced this item. + For custom tool calling, the type is always `custom`. - - `agent_name: string` + - `"custom"` - The canonical name of the agent that produced this item. + - `BetaSpecificProgrammaticToolCallingParam object { type }` - - `call_id: optional string` + - `type: "programmatic_tool_calling"` - The unique ID of the tool search call generated by the model. + The tool to call. Always `programmatic_tool_calling`. - - `execution: optional "server" or "client"` + - `"programmatic_tool_calling"` - Whether tool search was executed by the server or by the client. + - `BetaToolChoiceApplyPatch object { type }` - - `"server"` + Forces the model to call the apply_patch tool when executing a tool call. - - `"client"` + - `type: "apply_patch"` - - `status: optional "in_progress" or "completed" or "incomplete"` + The tool to call. Always `apply_patch`. - The status of the tool search output. + - `"apply_patch"` - - `"in_progress"` + - `BetaToolChoiceShell object { type }` - - `"completed"` + Forces the model to call the shell tool when a tool call is required. - - `"incomplete"` + - `type: "shell"` - - `AdditionalTools object { role, tools, type, 2 more }` + The tool to call. Always `shell`. - - `role: "developer"` + - `"shell"` - The role that provided the additional tools. Only `developer` is supported. + - `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` - - `"developer"` + 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. - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + We support the following categories of tools: - A list of additional tools made available at this item. + - **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. - `Function object { name, parameters, strict, 5 more }` @@ -186124,86 +186446,92 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"programmatic"` - - `type: "additional_tools"` - - The item type. Always `additional_tools`. - - - `"additional_tools"` - - - `id: optional string` - - The unique ID of this additional tools item. - - - `agent: optional object { agent_name }` + - `top_logprobs: optional number` - The agent that produced this item. + 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. - - `agent_name: string` + - `top_p: optional number` - The canonical name of the agent that produced this item. + 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. - - `Reasoning object { id, summary, type, 4 more }` + We generally recommend altering this or `temperature` but not both. - 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). + - `truncation: optional "auto" or "disabled"` - - `id: string` + The truncation strategy to use for the model response. - The unique identifier of the reasoning content. + - `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. - - `summary: array of object { text, type }` + - `"auto"` - Reasoning summary content. + - `"disabled"` - - `text: string` + - `user: optional string` - A summary of the reasoning output from the model so far. + 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: "summary_text"` + - `BetaResponseInjectEvent object { input, response_id, type }` - The type of the object. Always `summary_text`. + Injects input items into an active response over a WebSocket connection. + The items are validated and committed atomically. Currently, the server + accepts client-owned tool outputs that resume a waiting agent. - - `"summary_text"` + - `input: array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - - `type: "reasoning"` + Input items to inject into the active response. - The type of the object. Always `reasoning`. + - `BetaEasyInputMessage object { content, role, phase, type }` - - `"reasoning"` + 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. - - `agent: optional object { agent_name }` + - `Message object { content, role, agent, 2 more }` - The agent that produced this 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. - - `agent_name: string` + - `content: BetaResponseInputMessageContentList` - The canonical name of the agent that produced this item. + A list of one or many input items to the model, containing different content + types. - - `content: optional array of object { text, type }` + - `role: "user" or "system" or "developer"` - Reasoning text content. + The role of the message input. One of `user`, `system`, or `developer`. - - `text: string` + - `"user"` - The reasoning text from the model. + - `"system"` - - `type: "reasoning_text"` + - `"developer"` - The type of the reasoning text. Always `reasoning_text`. + - `agent: optional object { agent_name }` - - `"reasoning_text"` + The agent that produced this item. - - `encrypted_content: optional string` + - `agent_name: 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 canonical name of the agent that produced this item. - `status: optional "in_progress" or "completed" or "incomplete"` - The status of the item. One of `in_progress`, `completed`, or + The status of item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -186212,61 +186540,49 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `Compaction object { encrypted_content, type, id, agent }` - - 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. + - `type: optional "message"` - - `agent: optional object { agent_name }` + The type of the message input. Always set to `message`. - The agent that produced this item. + - `"message"` - - `agent_name: string` + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - The canonical name of the agent that produced this item. + An output message from the model. - - `ImageGenerationCall object { id, result, status, 2 more }` + - `FileSearchCall object { id, queries, status, 3 more }` - An image generation request made by the model. + 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 image generation call. + The unique ID of the file search tool call. - - `result: string` + - `queries: array of string` - The generated image encoded in base64. + The queries used to search for files. - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `status: "in_progress" or "searching" or "completed" or 2 more` - The status of the image generation call. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - `"in_progress"` + - `"searching"` + - `"completed"` - - `"generating"` + - `"incomplete"` - `"failed"` - - `type: "image_generation_call"` + - `type: "file_search_call"` - The type of the image generation call. Always `image_generation_call`. + The type of the file search tool call. Always `file_search_call`. - - `"image_generation_call"` + - `"file_search_call"` - `agent: optional object { agent_name }` @@ -186276,128 +186592,73 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `CodeInterpreterCall object { id, code, container_id, 4 more }` - - A tool call to run code. - - - `id: string` - - The unique ID of the code interpreter tool call. - - - `code: string` - - The code to run, or null if not available. - - - `container_id: string` - - The ID of the container used to run the code. - - - `outputs: array of object { logs, type } or object { type, url }` - - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. - - - `Logs object { logs, type }` - - The logs output from the code interpreter. - - - `logs: string` - - The logs output from the code interpreter. - - - `type: "logs"` - - The type of the output. Always `logs`. - - - `"logs"` - - - `Image object { type, url }` - - The image output from the code interpreter. - - - `type: "image"` - - The type of the output. Always `image`. - - - `"image"` - - - `url: string` - - The URL of the image output from the code interpreter. + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + The results of the file search tool call. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `attributes: optional map[string or number or boolean]` - - `"in_progress"` + 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. - - `"completed"` + - `string` - - `"incomplete"` + - `number` - - `"interpreting"` + - `boolean` - - `"failed"` + - `file_id: optional string` - - `type: "code_interpreter_call"` + The unique ID of the file. - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `filename: optional string` - - `"code_interpreter_call"` + The name of the file. - - `agent: optional object { agent_name }` + - `score: optional number` - The agent that produced this item. + The relevance score of the file - a value between 0 and 1. - - `agent_name: string` + - `text: optional string` - The canonical name of the agent that produced this item. + The text that was retrieved from the file. - - `LocalShellCall object { id, action, call_id, 3 more }` + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - A tool call to run a command on the local shell. + 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 local shell call. - - - `action: object { command, env, type, 3 more }` - - Execute a shell command on the server. - - - `command: array of string` - - The command to run. - - - `env: map[string]` - - Environment variables to set for the command. - - - `type: "exec"` + The unique ID of the computer call. - The type of the local shell action. Always `exec`. + - `call_id: string` - - `"exec"` + An identifier used when responding to the tool call with output. - - `timeout_ms: optional number` + - `pending_safety_checks: array of object { id, code, message }` - Optional timeout in milliseconds for the command. + The pending safety checks for the computer call. - - `user: optional string` + - `id: string` - Optional user to run the command as. + The ID of the pending safety check. - - `working_directory: optional string` + - `code: optional string` - Optional working directory to run the command in. + The type of the pending safety check. - - `call_id: string` + - `message: optional string` - The unique ID of the local shell tool call generated by the model. + Details about the pending safety check. - `status: "in_progress" or "completed" or "incomplete"` - The status of the local shell call. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -186405,37 +186666,20 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `type: "local_shell_call"` - - The type of the local shell call. Always `local_shell_call`. - - - `"local_shell_call"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `LocalShellCallOutput object { id, output, type, 2 more }` - - The output of a local shell tool call. - - - `id: string` + - `type: "computer_call"` - The unique ID of the local shell tool call generated by the model. + The type of the computer call. Always `computer_call`. - - `output: string` + - `"computer_call"` - A JSON string of the output of the local shell tool call. + - `action: optional BetaComputerAction` - - `type: "local_shell_call_output"` + A click action. - The type of the local shell tool call output. Always `local_shell_call_output`. + - `actions: optional BetaComputerActionList` - - `"local_shell_call_output"` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - `agent: optional object { agent_name }` @@ -186445,49 +186689,43 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - - `"in_progress"` - - - `"completed"` + - `ComputerCallOutput object { call_id, output, type, 4 more }` - - `"incomplete"` + The output of a computer tool call. - - `ShellCall object { action, call_id, type, 5 more }` + - `call_id: string` - A tool representing a request to execute one or more shell commands. + The ID of the computer tool call that produced the output. - - `action: object { commands, max_output_length, timeout_ms }` + - `output: BetaResponseComputerToolCallOutputScreenshot` - The shell commands and limits that describe how to run the tool call. + A computer screenshot image used with the computer use tool. - - `commands: array of string` + - `type: "computer_call_output"` - Ordered shell commands for the execution environment to run. + The type of the computer tool call output. Always `computer_call_output`. - - `max_output_length: optional number` + - `"computer_call_output"` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + - `id: optional string` - - `timeout_ms: optional number` + The ID of the computer tool call output. - Maximum wall-clock time in milliseconds to allow the shell commands to run. + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `call_id: string` + The safety checks reported by the API that have been acknowledged by the developer. - The unique ID of the shell tool call generated by the model. + - `id: string` - - `type: "shell_call"` + The ID of the pending safety check. - The type of the item. Always `shell_call`. + - `code: optional string` - - `"shell_call"` + The type of the pending safety check. - - `id: optional string` + - `message: optional string` - The unique ID of the shell tool call. Populated when this item is returned via API. + Details about the pending safety check. - `agent: optional object { agent_name }` @@ -186497,41 +186735,9 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. - - - `Direct object { type }` - - - `type: "direct"` - - The caller type. Always `direct`. - - - `"direct"` - - - `Program object { caller_id, type }` - - - `caller_id: string` - - The call ID of the program item that produced this tool call. - - - `type: "program"` - - The caller type. Always `program`. - - - `"program"` - - - `environment: optional BetaLocalEnvironment or BetaContainerReference` - - The environment to execute the shell commands in. - - - `BetaLocalEnvironment object { type, skills }` - - - `BetaContainerReference object { container_id, type }` - - `status: optional "in_progress" or "completed" or "incomplete"` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - `"in_progress"` @@ -186539,189 +186745,101 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `ShellCallOutput object { call_id, output, type, 5 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 BetaResponseFunctionShellCallOutputContent` - - Captured chunks of stdout and stderr output, along with their associated outcomes. - - - `outcome: object { type } or object { exit_code, type }` - - The exit or timeout outcome associated with this shell call. - - - `Timeout object { type }` - - Indicates that the shell call exceeded its configured time limit. + - `WebSearchCall object { id, action, status, 2 more }` - - `type: "timeout"` + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - The outcome type. Always `timeout`. + - `id: string` - - `"timeout"` + The unique ID of the web search tool call. - - `Exit object { exit_code, type }` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - Indicates that the shell commands finished and returned an exit code. + 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). - - `exit_code: number` + - `Search object { type, queries, query, sources }` - The exit code returned by the shell process. + Action type "search" - Performs a web search query. - - `type: "exit"` + - `type: "search"` - The outcome type. Always `exit`. + The action type. - - `"exit"` + - `"search"` - - `stderr: string` + - `queries: optional array of string` - Captured stderr output for the shell call. + The search queries. - - `stdout: string` + - `query: optional string` - Captured stdout output for the shell call. + The search query. - - `type: "shell_call_output"` + - `sources: optional array of object { type, url }` - The type of the item. Always `shell_call_output`. + The sources used in the search. - - `"shell_call_output"` + - `type: "url"` - - `id: optional string` + The type of source. Always `url`. - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `"url"` - - `agent: optional object { agent_name }` + - `url: string` - The agent that produced this item. + The URL of the source. - - `agent_name: string` + - `OpenPage object { type, url }` - The canonical name of the agent that produced this item. + Action type "open_page" - Opens a specific URL from search results. - - `caller: optional object { type } or object { caller_id, type }` + - `type: "open_page"` - The execution context that produced this tool call. + The action type. - - `Direct object { type }` + - `"open_page"` - - `type: "direct"` + - `url: optional string` - The caller type. Always `direct`. + The URL opened by the model. - - `"direct"` + - `FindInPage object { pattern, type, url }` - - `Program object { caller_id, type }` + Action type "find_in_page": Searches for a pattern within a loaded page. - - `caller_id: string` + - `pattern: string` - The call ID of the program item that produced this tool call. + The pattern or text to search for within the page. - - `type: "program"` + - `type: "find_in_page"` - The caller type. Always `program`. + The action type. - - `"program"` + - `"find_in_page"` - - `max_output_length: optional number` + - `url: string` - The maximum number of UTF-8 characters captured for this shell call's combined output. + The URL of the page searched for the pattern. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `status: "in_progress" or "searching" or "completed" or "failed"` - The status of the shell call output. + The status of the web search tool call. - `"in_progress"` - - `"completed"` - - - `"incomplete"` - - - `ApplyPatchCall object { call_id, operation, status, 4 more }` - - A tool call representing a request to create, delete, or update files using diff patches. - - - `call_id: string` - - The unique ID of the apply patch tool call generated by the model. - - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - The specific create, delete, or update instruction for the apply_patch tool call. - - - `CreateFile object { diff, path, type }` - - Instruction for creating a new file via the apply_patch tool. - - - `diff: string` - - Unified diff content to apply when creating the file. - - - `path: string` - - Path of the file to create relative to the workspace root. - - - `type: "create_file"` - - The operation type. Always `create_file`. - - - `"create_file"` - - - `DeleteFile object { path, type }` - - Instruction for deleting an existing file via the apply_patch tool. - - - `path: string` - - Path of the file to delete relative to the workspace root. - - - `type: "delete_file"` - - The operation type. Always `delete_file`. - - - `"delete_file"` - - - `UpdateFile object { diff, path, type }` - - Instruction for updating an existing file via the apply_patch tool. - - - `diff: string` - - Unified diff content to apply to the existing file. - - - `path: string` - - Path of the file to update relative to the workspace root. - - - `type: "update_file"` - - The operation type. Always `update_file`. - - - `"update_file"` - - - `status: "in_progress" or "completed"` - - The status of the apply patch tool call. One of `in_progress` or `completed`. - - - `"in_progress"` + - `"searching"` - `"completed"` - - `type: "apply_patch_call"` - - The type of the item. Always `apply_patch_call`. + - `"failed"` - - `"apply_patch_call"` + - `type: "web_search_call"` - - `id: optional string` + The type of the web search tool call. Always `web_search_call`. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `"web_search_call"` - `agent: optional object { agent_name }` @@ -186731,55 +186849,32 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `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`. + - `FunctionCall object { arguments, call_id, name, 6 more }` - - `"program"` + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` + - `arguments: string` - The streamed output emitted by an apply patch tool call. + A JSON string of the arguments to pass to the function. - `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`. + The unique ID of the function tool call generated by the model. - - `"completed"` + - `name: string` - - `"failed"` + The name of the function to run. - - `type: "apply_patch_call_output"` + - `type: "function_call"` - The type of the item. Always `apply_patch_call_output`. + The type of the function tool call. Always `function_call`. - - `"apply_patch_call_output"` + - `"function_call"` - `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. - `agent: optional object { agent_name }` @@ -186797,8 +186892,6 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "direct"` - The caller type. Always `direct`. - - `"direct"` - `Program object { caller_id, type }` @@ -186809,182 +186902,16 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "program"` - The caller type. Always `program`. - - `"program"` - - `output: optional string` - - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - - `McpListTools object { id, server_label, tools, 3 more }` - - A list of tools available on an MCP server. - - - `id: string` - - The unique ID of the list. - - - `server_label: string` - - The label of the MCP server. - - - `tools: array of object { input_schema, name, annotations, description }` - - The tools available on the server. - - - `input_schema: unknown` - - The JSON schema describing the tool's input. - - - `name: string` - - The name of the tool. - - - `annotations: optional unknown` - - Additional annotations about the tool. - - - `description: optional string` - - The description of the tool. - - - `type: "mcp_list_tools"` - - The type of the item. Always `mcp_list_tools`. - - - `"mcp_list_tools"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `error: optional string` - - Error message if the server could not list tools. - - - `McpApprovalRequest object { id, arguments, name, 3 more }` - - A request for human approval of a tool invocation. - - - `id: string` - - The unique ID of the approval request. - - - `arguments: string` - - A JSON string of arguments for the tool. - - - `name: string` - - The name of the tool to run. - - - `server_label: string` - - The label of the MCP server making the request. - - - `type: "mcp_approval_request"` - - The type of the item. Always `mcp_approval_request`. - - - `"mcp_approval_request"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` - - A response to an MCP approval request. - - - `approval_request_id: string` - - The ID of the approval request being answered. - - - `approve: boolean` - - Whether the request was approved. - - - `type: "mcp_approval_response"` - - The type of the item. Always `mcp_approval_response`. - - - `"mcp_approval_response"` - - - `id: optional string` - - The unique ID of the approval response - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `reason: optional string` - - Optional reason for the decision. - - - `McpCall object { id, arguments, name, 7 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"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `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` + - `namespace: optional string` - The output from the tool call. + The namespace of the function to run. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `status: optional "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 item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - `"in_progress"` @@ -186992,52 +186919,47 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `"calling"` - - - `"failed"` - - - `CustomToolCallOutput object { call_id, output, type, 3 more }` + - `FunctionCallOutput object { call_id, output, type, 4 more }` - The output of a custom tool call from your code, being sent back to the model. + The output of a function tool call. - `call_id: string` - The call ID, used to map this custom tool call output to a custom tool call. + The unique ID of the function tool call generated by the model. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + Text, image, or file output of the function tool call. - - `StringOutput = string` + - `string` - A string of the output of the custom tool call. + A JSON string of the output of the function tool call. - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - Text, image, or file output of the custom tool call. + An array of content outputs (text, image, file) for the function tool call. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` A text input to the model. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `BetaResponseInputImageContent 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) - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` A file input to the model. - - `type: "custom_tool_call_output"` + - `type: "function_call_output"` - The type of the custom tool call output. Always `custom_tool_call_output`. + The type of the function tool call output. Always `function_call_output`. - - `"custom_tool_call_output"` + - `"function_call_output"` - `id: optional string` - The unique ID of the custom tool call output in the OpenAI platform. + The unique ID of the function tool call output. Populated when this item is returned via API. - `agent: optional object { agent_name }` @@ -187071,73 +186993,63 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"program"` - - `CustomToolCall object { call_id, input, name, 5 more }` - - A call to a custom tool created by the model. - - - `call_id: string` - - An identifier used to map this custom tool call to a tool call output. - - - `input: string` - - The input for the custom tool call generated by the model. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `name: string` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - The name of the custom tool being called. + - `"in_progress"` - - `type: "custom_tool_call"` + - `"completed"` - The type of the custom tool call. Always `custom_tool_call`. + - `"incomplete"` - - `"custom_tool_call"` + - `AgentMessage object { author, content, recipient, 3 more }` - - `id: optional string` + A message routed between agents. - The unique ID of the custom tool call in the OpenAI platform. + - `author: string` - - `agent: optional object { agent_name }` + The sending agent identity. - The agent that produced this item. + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - - `agent_name: string` + Plaintext, image, or encrypted content sent between agents. - The canonical name of the agent that produced this item. + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - - `caller: optional object { type } or object { caller_id, type }` + A text input to the model. - The execution context that produced this tool call. + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - - `Direct object { type }` + An image input to the model. Learn about [image inputs](/docs/guides/vision) - - `type: "direct"` + - `EncryptedContent object { encrypted_content, type }` - - `"direct"` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `Program object { caller_id, type }` + - `encrypted_content: string` - - `caller_id: string` + Opaque encrypted content. - The call ID of the program item that produced this tool call. + - `type: "encrypted_content"` - - `type: "program"` + The type of the input item. Always `encrypted_content`. - - `"program"` + - `"encrypted_content"` - - `namespace: optional string` + - `recipient: string` - The namespace of the custom tool being called. + The destination agent identity. - - `CompactionTrigger object { type, agent }` + - `type: "agent_message"` - Compacts the current context. Must be the final input item. + The item type. Always `agent_message`. - - `type: "compaction_trigger"` + - `"agent_message"` - The type of the item. Always `compaction_trigger`. + - `id: optional string` - - `"compaction_trigger"` + The unique ID of this agent message item. - `agent: optional object { agent_name }` @@ -187147,51 +187059,41 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `ItemReference object { id, agent, type }` - - An internal identifier for an item to reference. - - - `id: string` - - The ID of the item to reference. + - `MultiAgentCall object { action, arguments, call_id, 3 more }` - - `agent: optional object { agent_name }` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - The agent that produced this item. + The multi-agent action that was executed. - - `agent_name: string` + - `"spawn_agent"` - The canonical name of the agent that produced this item. + - `"interrupt_agent"` - - `type: optional "item_reference"` + - `"list_agents"` - The type of item to reference. Always `item_reference`. + - `"send_message"` - - `"item_reference"` + - `"followup_task"` - - `Program object { id, call_id, code, 3 more }` + - `"wait_agent"` - - `id: string` + - `arguments: string` - The unique ID of this program item. + The action arguments as a JSON string. - `call_id: string` - The stable call ID of the program item. - - - `code: string` - - The JavaScript source executed by programmatic tool calling. + The unique ID linking this call to its output. - - `fingerprint: string` + - `type: "multi_agent_call"` - Opaque program replay fingerprint that must be round-tripped. + The item type. Always `multi_agent_call`. - - `type: "program"` + - `"multi_agent_call"` - The item type. Always `program`. + - `id: optional string` - - `"program"` + The unique ID of this multi-agent call. - `agent: optional object { agent_name }` @@ -187201,1162 +187103,1186 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `ProgramOutput object { id, call_id, result, 3 more }` + - `MultiAgentCallOutput object { action, call_id, output, 3 more }` - - `id: string` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - The unique ID of this program output item. + The multi-agent action that produced this result. + + - `"spawn_agent"` + + - `"interrupt_agent"` + + - `"list_agents"` + + - `"send_message"` + + - `"followup_task"` + + - `"wait_agent"` - `call_id: string` - The call ID of the program item. + The unique ID of the multi-agent call. - - `result: string` + - `output: array of object { text, type, annotations }` - The result produced by the program item. + Text output returned by the multi-agent action. - - `status: "completed" or "incomplete"` + - `text: string` - The terminal status of the program output. + The text content. - - `"completed"` + - `type: "output_text"` - - `"incomplete"` + The content type. Always `output_text`. - - `type: "program_output"` + - `"output_text"` - The item type. Always `program_output`. + - `annotations: optional 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 }` - - `"program_output"` + Citations associated with the text content. - - `agent: optional object { agent_name }` + - `FileCitation object { file_id, filename, index, type }` - The agent that produced this item. + - `file_id: string` - - `agent_name: string` + The ID of the file. - The canonical name of the agent that produced this item. + - `filename: string` - - `metadata: map[string]` + The filename of the file cited. - 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. + - `index: number` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The index of the file in the list of files. - - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` + - `type: "file_citation"` - 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. + The citation type. Always `file_citation`. - - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` + - `"file_citation"` + + - `URLCitation object { end_index, start_index, title, 2 more }` - 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. + - `end_index: number` - - `"gpt-5.6-sol"` + The index of the last character of the citation in the message. - - `"gpt-5.6-terra"` + - `start_index: number` - - `"gpt-5.6-luna"` + The index of the first character of the citation in the message. - - `"gpt-5.4"` + - `title: string` - - `"gpt-5.4-mini"` + The title of the cited resource. - - `"gpt-5.4-nano"` + - `type: "url_citation"` - - `"gpt-5.4-mini-2026-03-17"` + The citation type. Always `url_citation`. - - `"gpt-5.4-nano-2026-03-17"` + - `"url_citation"` - - `"gpt-5.3-chat-latest"` + - `url: string` - - `"gpt-5.2"` + The URL of the cited resource. - - `"gpt-5.2-2025-12-11"` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - - `"gpt-5.2-chat-latest"` + - `container_id: string` - - `"gpt-5.2-pro"` + The ID of the container. - - `"gpt-5.2-pro-2025-12-11"` + - `end_index: number` - - `"gpt-5.1"` + The index of the last character of the citation in the message. - - `"gpt-5.1-2025-11-13"` + - `file_id: string` - - `"gpt-5.1-codex"` + The ID of the container file. - - `"gpt-5.1-mini"` + - `filename: string` - - `"gpt-5.1-chat-latest"` + The filename of the container file cited. - - `"gpt-5"` + - `start_index: number` - - `"gpt-5-mini"` + The index of the first character of the citation in the message. - - `"gpt-5-nano"` + - `type: "container_file_citation"` - - `"gpt-5-2025-08-07"` + The citation type. Always `container_file_citation`. - - `"gpt-5-mini-2025-08-07"` + - `"container_file_citation"` - - `"gpt-5-nano-2025-08-07"` + - `type: "multi_agent_call_output"` - - `"gpt-5-chat-latest"` + The item type. Always `multi_agent_call_output`. - - `"gpt-4.1"` + - `"multi_agent_call_output"` - - `"gpt-4.1-mini"` + - `id: optional string` - - `"gpt-4.1-nano"` + The unique ID of this multi-agent call output. - - `"gpt-4.1-2025-04-14"` + - `agent: optional object { agent_name }` - - `"gpt-4.1-mini-2025-04-14"` + The agent that produced this item. - - `"gpt-4.1-nano-2025-04-14"` + - `agent_name: string` - - `"o4-mini"` + The canonical name of the agent that produced this item. - - `"o4-mini-2025-04-16"` + - `ToolSearchCall object { arguments, type, id, 4 more }` - - `"o3"` + - `arguments: unknown` - - `"o3-2025-04-16"` + The arguments supplied to the tool search call. - - `"o3-mini"` + - `type: "tool_search_call"` - - `"o3-mini-2025-01-31"` + The item type. Always `tool_search_call`. - - `"o1"` + - `"tool_search_call"` - - `"o1-2024-12-17"` + - `id: optional string` - - `"o1-preview"` + The unique ID of this tool search call. - - `"o1-preview-2024-09-12"` + - `agent: optional object { agent_name }` - - `"o1-mini"` + The agent that produced this item. - - `"o1-mini-2024-09-12"` + - `agent_name: string` - - `"gpt-4o"` + The canonical name of the agent that produced this item. - - `"gpt-4o-2024-11-20"` + - `call_id: optional string` - - `"gpt-4o-2024-08-06"` + The unique ID of the tool search call generated by the model. - - `"gpt-4o-2024-05-13"` + - `execution: optional "server" or "client"` - - `"gpt-4o-audio-preview"` + Whether tool search was executed by the server or by the client. - - `"gpt-4o-audio-preview-2024-10-01"` + - `"server"` - - `"gpt-4o-audio-preview-2024-12-17"` + - `"client"` - - `"gpt-4o-audio-preview-2025-06-03"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"gpt-4o-mini-audio-preview"` + The status of the tool search call. - - `"gpt-4o-mini-audio-preview-2024-12-17"` + - `"in_progress"` - - `"gpt-4o-search-preview"` + - `"completed"` - - `"gpt-4o-mini-search-preview"` + - `"incomplete"` - - `"gpt-4o-search-preview-2025-03-11"` + - `ToolSearchOutput object { tools, type, id, 4 more }` - - `"gpt-4o-mini-search-preview-2025-03-11"` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - - `"chatgpt-4o-latest"` + The loaded tool definitions returned by the tool search output. - - `"codex-mini-latest"` + - `Function object { name, parameters, strict, 5 more }` - - `"gpt-4o-mini"` + 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). - - `"gpt-4o-mini-2024-07-18"` + - `name: string` - - `"gpt-4-turbo"` + The name of the function to call. - - `"gpt-4-turbo-2024-04-09"` + - `parameters: map[unknown]` - - `"gpt-4-0125-preview"` + A JSON schema object describing the parameters of the function. - - `"gpt-4-turbo-preview"` + - `strict: boolean` - - `"gpt-4-1106-preview"` + Whether strict parameter validation is enforced for this function tool. - - `"gpt-4-vision-preview"` + - `type: "function"` - - `"gpt-4"` + The type of the function tool. Always `function`. - - `"gpt-4-0314"` + - `"function"` - - `"gpt-4-0613"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"gpt-4-32k"` + The tool invocation context(s). - - `"gpt-4-32k-0314"` + - `"direct"` - - `"gpt-4-32k-0613"` + - `"programmatic"` - - `"gpt-3.5-turbo"` + - `defer_loading: optional boolean` - - `"gpt-3.5-turbo-16k"` + Whether this function is deferred and loaded via tool search. - - `"gpt-3.5-turbo-0301"` + - `description: optional string` - - `"gpt-3.5-turbo-0613"` + A description of the function. Used by the model to determine whether or not to call the function. - - `"gpt-3.5-turbo-1106"` + - `output_schema: optional map[unknown]` - - `"gpt-3.5-turbo-0125"` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `"gpt-3.5-turbo-16k-0613"` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `"o1-pro"` + 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). - - `"o1-pro-2025-03-19"` + - `type: "file_search"` - - `"o3-pro"` + The type of the file search tool. Always `file_search`. - - `"o3-pro-2025-06-10"` + - `"file_search"` - - `"o3-deep-research"` + - `vector_store_ids: array of string` - - `"o3-deep-research-2025-06-26"` + The IDs of the vector stores to search. - - `"o4-mini-deep-research"` + - `filters: optional object { key, type, value } or object { filters, type }` - - `"o4-mini-deep-research-2025-06-26"` + A filter to apply. - - `"computer-use-preview"` + - `ComparisonFilter object { key, type, value }` - - `"computer-use-preview-2025-03-11"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"gpt-5-codex"` + - `key: string` - - `"gpt-5-pro"` + The key to compare against the value. - - `"gpt-5-pro-2025-10-06"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `"gpt-5.1-codex-max"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `string` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `object: "response"` + - `"eq"` - The object type of this resource - always set to `response`. + - `"ne"` - - `"response"` + - `"gt"` - - `output: array of BetaResponseOutputItem` + - `"gte"` - An array of content items generated by the model. + - `"lt"` - - 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. + - `"lte"` - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + - `"in"` - An output message from the model. + - `"nin"` - - `FileSearchCall object { id, queries, status, 3 more }` + - `value: string or number or boolean or array of string or number` - The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + The value to compare against the attribute key; supports string, number, or boolean types. - - `id: string` + - `string` - The unique ID of the file search tool call. + - `number` - - `queries: array of string` + - `boolean` - The queries used to search for files. + - `array of string or number` - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `string` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `number` - - `"in_progress"` + - `CompoundFilter object { filters, type }` - - `"searching"` + Combine multiple filters using `and` or `or`. - - `"completed"` + - `filters: array of object { key, type, value } or unknown` - - `"incomplete"` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `"failed"` + - `ComparisonFilter object { key, type, value }` - - `type: "file_search_call"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The type of the file search tool call. Always `file_search_call`. + - `key: string` - - `"file_search_call"` + The key to compare against the value. - - `agent: optional object { agent_name }` + - `type: "eq" or "ne" or "gt" or 5 more` - The agent that produced this item. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `agent_name: string` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - The canonical name of the agent that produced this item. + - `"eq"` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `"ne"` - The results of the file search tool call. + - `"gt"` - - `attributes: optional map[string or number or boolean]` + - `"gte"` - 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. + - `"lt"` - - `string` + - `"lte"` - - `number` + - `"in"` - - `boolean` + - `"nin"` - - `file_id: optional string` + - `value: string or number or boolean or array of string or number` - The unique ID of the file. + The value to compare against the attribute key; supports string, number, or boolean types. - - `filename: optional string` + - `string` - The name of the file. + - `number` - - `score: optional number` + - `boolean` - The relevance score of the file - a value between 0 and 1. + - `array of string or number` - - `text: optional string` + - `string` - The text that was retrieved from the file. + - `number` - - `FunctionCall object { arguments, call_id, name, 6 more }` + - `unknown` - A tool call to run a function. See the - [function calling guide](/docs/guides/function-calling) for more information. + - `type: "and" or "or"` - - `arguments: string` + Type of operation: `and` or `or`. - A JSON string of the arguments to pass to the function. + - `"and"` - - `call_id: string` + - `"or"` - The unique ID of the function tool call generated by the model. + - `max_num_results: optional number` - - `name: string` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - The name of the function to run. + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `type: "function_call"` + Ranking options for search. - The type of the function tool call. Always `function_call`. + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `"function_call"` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `id: optional string` + - `embedding_weight: number` - The unique ID of the function tool call. + The weight of the embedding in the reciprocal ranking fusion. - - `agent: optional object { agent_name }` + - `text_weight: number` - The agent that produced this item. + The weight of the text in the reciprocal ranking fusion. - - `agent_name: string` + - `ranker: optional "auto" or "default-2024-11-15"` - The canonical name of the agent that produced this item. + The ranker to use for the file search. - - `caller: optional object { type } or object { caller_id, type }` + - `"auto"` - The execution context that produced this tool call. + - `"default-2024-11-15"` - - `Direct object { type }` + - `score_threshold: optional number` - - `type: "direct"` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - - `"direct"` + - `Computer object { type }` - - `Program object { caller_id, type }` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `caller_id: string` + - `type: "computer"` - The call ID of the program item that produced this tool call. + The type of the computer tool. Always `computer`. - - `type: "program"` + - `"computer"` - - `"program"` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `namespace: optional string` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The namespace of the function to run. + - `display_height: number` - - `status: optional "in_progress" or "completed" or "incomplete"` + The height of the computer display. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `display_width: number` - - `"in_progress"` + The width of the computer display. - - `"completed"` + - `environment: "windows" or "mac" or "linux" or 2 more` - - `"incomplete"` + The type of computer environment to control. - - `FunctionCallOutput object { id, call_id, output, 5 more }` + - `"windows"` - - `id: string` + - `"mac"` - The unique ID of the function call tool output. + - `"linux"` - - `call_id: string` + - `"ubuntu"` - The unique ID of the function tool call generated by the model. + - `"browser"` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `type: "computer_use_preview"` - The output from the function call generated by your code. - Can be a string or an list of output content. + The type of the computer use tool. Always `computer_use_preview`. - - `StringOutput = string` + - `"computer_use_preview"` - A string of the output of the function call. + - `WebSearch object { type, filters, search_context_size, user_location }` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - Text, image, or file output of the function call. + - `type: "web_search" or "web_search_2025_08_26"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - A text input to the model. + - `"web_search"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `"web_search_2025_08_26"` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `filters: optional object { allowed_domains }` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + Filters for the search. - A file input to the model. + - `allowed_domains: optional array of string` - - `status: "in_progress" or "completed" or "incomplete"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `"in_progress"` + - `search_context_size: optional "low" or "medium" or "high"` - - `"completed"` + 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. - - `"incomplete"` + - `"low"` - - `type: "function_call_output"` + - `"medium"` - The type of the function tool call output. Always `function_call_output`. + - `"high"` - - `"function_call_output"` + - `user_location: optional object { city, country, region, 2 more }` - - `agent: optional object { agent_name }` + The approximate location of the user. - The agent that produced this item. + - `city: optional string` - - `agent_name: string` + Free text input for the city of the user, e.g. `San Francisco`. - The canonical name of the agent that produced this item. + - `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` - The caller type. Always `direct`. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"direct"` + - `type: optional "approximate"` - - `Program object { caller_id, type }` + The type of location approximation. Always `approximate`. - - `caller_id: string` + - `"approximate"` - The call ID of the program item that produced this tool call. + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `type: "program"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - The caller type. Always `program`. + - `server_label: string` - - `"program"` + A label for this MCP server, used to identify it in tool calls. - - `created_by: optional string` + - `type: "mcp"` - The identifier of the actor that created the item. + The type of the MCP tool. Always `mcp`. - - `AgentMessage object { id, author, content, 3 more }` + - `"mcp"` - - `id: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The unique ID of the agent message. + The tool invocation context(s). - - `author: string` + - `"direct"` - The sending agent identity. + - `"programmatic"` - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - Encrypted content sent between agents. + List of allowed tool names or a filter object. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `McpAllowedTools = array of string` - A text input to the model. + A string array of allowed tool names - - `BetaResponseOutputText object { annotations, logprobs, text, type }` + - `McpToolFilter object { read_only, tool_names }` - A text output from the model. + A filter object to specify which tools are allowed. - - `Text object { text, type }` + - `read_only: optional boolean` - A text content. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `text: string` + - `tool_names: optional array of string` - - `type: "text"` + List of allowed tool names. - - `"text"` + - `authorization: optional string` - - `SummaryText object { text, type }` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - A summary text from the model. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `text: 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). - A summary of the reasoning output from the model so far. + Currently supported `connector_id` values are: - - `type: "summary_text"` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - The type of the object. Always `summary_text`. + - `"connector_dropbox"` - - `"summary_text"` + - `"connector_gmail"` - - `ReasoningText object { text, type }` + - `"connector_googlecalendar"` - Reasoning text from the model. + - `"connector_googledrive"` - - `text: string` + - `"connector_microsoftteams"` - The reasoning text from the model. + - `"connector_outlookcalendar"` - - `type: "reasoning_text"` + - `"connector_outlookemail"` - The type of the reasoning text. Always `reasoning_text`. + - `"connector_sharepoint"` - - `"reasoning_text"` + - `defer_loading: optional boolean` - - `BetaResponseOutputRefusal object { refusal, type }` + Whether this MCP tool is deferred and discovered via tool search. - A refusal from the model. + - `headers: optional map[string]` - - `BetaResponseInputImage 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"` - - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` + Specify which of the MCP server's tools require approval. - A screenshot of a computer. + - `McpToolApprovalFilter object { always, never }` - - `detail: "low" or "high" or "auto" or "original"` + 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 detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `always: optional object { read_only, tool_names }` - - `"low"` + A filter object to specify which tools are allowed. - - `"high"` + - `read_only: optional boolean` - - `"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. - - `"original"` + - `tool_names: optional array of string` - - `file_id: string` + List of allowed tool names. - The identifier of an uploaded file that contains the screenshot. + - `never: optional object { read_only, tool_names }` - - `image_url: string` + A filter object to specify which tools are allowed. - The URL of the screenshot image. + - `read_only: optional boolean` - - `type: "computer_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. - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `tool_names: optional array of string` - - `"computer_screenshot"` + List of allowed tool names. - - `prompt_cache_breakpoint: optional object { mode }` + - `McpToolApprovalSetting = "always" or "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. + 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. - - `mode: "explicit"` + - `"always"` - The breakpoint mode. Always `explicit`. + - `"never"` - - `"explicit"` + - `server_description: optional string` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + Optional description of the MCP server, used to provide more context. - A file input to the model. + - `server_url: optional string` - - `EncryptedContent object { encrypted_content, type }` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `tunnel_id: optional string` - - `encrypted_content: string` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - Opaque encrypted content. + - `CodeInterpreter object { container, type, allowed_callers }` - - `type: "encrypted_content"` + A tool that runs Python code to help generate a response to a prompt. - The type of the input item. Always `encrypted_content`. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `"encrypted_content"` + 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. - - `recipient: string` + - `string` - The destination agent identity. + The container ID. - - `type: "agent_message"` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - The type of the item. Always `agent_message`. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `"agent_message"` + - `type: "auto"` - - `agent: optional object { agent_name }` + Always `auto`. - The agent that produced this item. + - `"auto"` - - `agent_name: string` + - `file_ids: optional array of string` - The canonical name of the agent that produced this item. + An optional list of uploaded files to make available to your code. - - `MultiAgentCall object { id, action, arguments, 3 more }` + - `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 multi-agent call item. + - `"1g"` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `"4g"` - The multi-agent action to execute. + - `"16g"` - - `"spawn_agent"` + - `"64g"` - - `"interrupt_agent"` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `"list_agents"` + Network access policy for the container. - - `"send_message"` + - `BetaContainerNetworkPolicyDisabled object { type }` - - `"followup_task"` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `"wait_agent"` + - `type: "code_interpreter"` - - `arguments: string` + The type of the code interpreter tool. Always `code_interpreter`. - The JSON string of arguments generated for the action. + - `"code_interpreter"` - - `call_id: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The unique ID linking this call to its output. + The tool invocation context(s). - - `type: "multi_agent_call"` + - `"direct"` - The type of the multi-agent call. Always `multi_agent_call`. + - `"programmatic"` - - `"multi_agent_call"` + - `ProgrammaticToolCalling object { type }` - - `agent: optional object { agent_name }` + - `type: "programmatic_tool_calling"` - The agent that produced this item. + The type of the tool. Always `programmatic_tool_calling`. - - `agent_name: string` + - `"programmatic_tool_calling"` - The canonical name of the agent that produced this item. + - `ImageGeneration object { type, action, background, 9 more }` - - `MultiAgentCallOutput object { id, action, call_id, 3 more }` + A tool that generates images using the GPT image models. - - `id: string` + - `type: "image_generation"` - The unique ID of the multi-agent call output item. + The type of the image generation tool. Always `image_generation`. - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `"image_generation"` - The multi-agent action that produced this result. + - `action: optional "generate" or "edit" or "auto"` - - `"spawn_agent"` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `"interrupt_agent"` + - `"generate"` - - `"list_agents"` + - `"edit"` - - `"send_message"` + - `"auto"` - - `"followup_task"` + - `background: optional "transparent" or "opaque" or "auto"` - - `"wait_agent"` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `call_id: string` + - `"transparent"` - The unique ID of the multi-agent call. + - `"opaque"` - - `output: array of BetaResponseOutputText` + - `"auto"` - Text output returned by the multi-agent action. + - `input_fidelity: optional "high" or "low"` - - `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 }` + 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 annotations of the text output. + - `"high"` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `"low"` - - `text: string` + - `input_image_mask: optional object { file_id, image_url }` - The text output from the model. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `type: "output_text"` + - `file_id: optional string` - The type of the output text. Always `output_text`. + File ID for the mask image. - - `type: "multi_agent_call_output"` + - `image_url: optional string` - The type of the multi-agent result. Always `multi_agent_call_output`. + Base64-encoded mask image. - - `"multi_agent_call_output"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `agent: optional object { agent_name }` + The image generation model to use. Default: `gpt-image-1`. - The agent that produced this item. + - `string` - - `agent_name: string` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The canonical name of the agent that produced this item. + The image generation model to use. Default: `gpt-image-1`. - - `WebSearchCall object { id, action, status, 2 more }` + - `"gpt-image-1"` - The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + - `"gpt-image-1-mini"` - - `id: string` + - `"gpt-image-1.5"` - The unique ID of the web search tool call. + - `moderation: optional "auto" or "low"` - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + Moderation level for the generated image. Default: `auto`. - 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). + - `"auto"` - - `Search object { type, queries, query, sources }` + - `"low"` - Action type "search" - Performs a web search query. + - `output_compression: optional number` - - `type: "search"` + Compression level for the output image. Default: 100. - The action type. + - `output_format: optional "png" or "webp" or "jpeg"` - - `"search"` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `queries: optional array of string` + - `"png"` - The search queries. + - `"webp"` - - `query: optional string` + - `"jpeg"` - The search query. + - `partial_images: optional number` - - `sources: optional array of object { type, url }` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The sources used in the search. + - `quality: optional "low" or "medium" or "high" or "auto"` - - `type: "url"` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - The type of source. Always `url`. + - `"low"` - - `"url"` + - `"medium"` - - `url: string` + - `"high"` - The URL of the source. + - `"auto"` - - `OpenPage object { type, url }` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - Action type "open_page" - Opens a specific URL from search results. + 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: "open_page"` + - `string` - The action type. + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `"open_page"` + 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: optional string` + - `"1024x1024"` - The URL opened by the model. + - `"1024x1536"` - - `FindInPage object { pattern, type, url }` + - `"1536x1024"` - Action type "find_in_page": Searches for a pattern within a loaded page. + - `"auto"` - - `pattern: string` + - `LocalShell object { type }` - The pattern or text to search for within the page. + A tool that allows the model to execute shell commands in a local environment. - - `type: "find_in_page"` + - `type: "local_shell"` - The action type. + The type of the local shell tool. Always `local_shell`. - - `"find_in_page"` + - `"local_shell"` - - `url: string` + - `Shell object { type, allowed_callers, environment }` - The URL of the page searched for the pattern. + A tool that allows the model to execute shell commands. - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `type: "shell"` - The status of the web search tool call. + The type of the shell tool. Always `shell`. - - `"in_progress"` + - `"shell"` - - `"searching"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"completed"` + The tool invocation context(s). - - `"failed"` + - `"direct"` - - `type: "web_search_call"` + - `"programmatic"` - The type of the web search tool call. Always `web_search_call`. + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `"web_search_call"` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `agent: optional object { agent_name }` + - `BetaLocalEnvironment object { type, skills }` - The agent that produced this item. + - `BetaContainerReference object { container_id, type }` - - `agent_name: string` + - `Custom object { name, type, allowed_callers, 3 more }` - The canonical name of the agent that produced this item. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + - `name: string` - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + The name of the custom tool, used to identify it in tool calls. - - `id: string` + - `type: "custom"` - The unique ID of the computer call. + The type of the custom tool. Always `custom`. - - `call_id: string` + - `"custom"` - An identifier used when responding to the tool call with output. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `pending_safety_checks: array of object { id, code, message }` + The tool invocation context(s). - The pending safety checks for the computer call. + - `"direct"` - - `id: string` + - `"programmatic"` - The ID of the pending safety check. + - `defer_loading: optional boolean` - - `code: optional string` + Whether this tool should be deferred and discovered via tool search. - The type of the pending safety check. + - `description: optional string` - - `message: optional string` + Optional description of the custom tool, used to provide more context. - Details about the pending safety check. + - `format: optional object { type } or object { definition, syntax, type }` - - `status: "in_progress" or "completed" or "incomplete"` + The input format for the custom tool. Default is unconstrained text. - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `Text object { type }` - - `"in_progress"` + Unconstrained free-form text. - - `"completed"` + - `type: "text"` - - `"incomplete"` + Unconstrained text format. Always `text`. - - `type: "computer_call"` + - `"text"` - The type of the computer call. Always `computer_call`. + - `Grammar object { definition, syntax, type }` - - `"computer_call"` + A grammar defined by the user. - - `action: optional BetaComputerAction` + - `definition: string` - A click action. + The grammar definition. - - `actions: optional BetaComputerActionList` + - `syntax: "lark" or "regex"` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + The syntax of the grammar definition. One of `lark` or `regex`. - - `agent: optional object { agent_name }` + - `"lark"` - The agent that produced this item. + - `"regex"` - - `agent_name: string` + - `type: "grammar"` - The canonical name of the agent that produced this item. + Grammar format. Always `grammar`. - - `ComputerCallOutput object { id, call_id, output, 5 more }` + - `"grammar"` - - `id: string` + - `Namespace object { description, name, tools, type }` - The unique ID of the computer call tool output. + Groups function/custom tools under a shared namespace. - - `call_id: string` + - `description: string` - The ID of the computer tool call that produced the output. + A description of the namespace shown to the model. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `name: string` - A computer screenshot image used with the computer use tool. + The namespace name used in tool calls (for example, `crm`). - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + The function/custom tools available inside this namespace. - - `"completed"` + - `Function object { name, type, allowed_callers, 5 more }` - - `"incomplete"` + - `name: string` - - `"failed"` + - `type: "function"` - - `"in_progress"` + - `"function"` - - `type: "computer_call_output"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The type of the computer tool call output. Always `computer_call_output`. + The tool invocation context(s). - - `"computer_call_output"` + - `"direct"` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `"programmatic"` - The safety checks reported by the API that have been acknowledged by the - developer. + - `defer_loading: optional boolean` - - `id: string` + Whether this function should be deferred and discovered via tool search. - The ID of the pending safety check. + - `description: optional string` - - `code: optional string` + - `output_schema: optional map[unknown]` - The type of the pending safety check. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `message: optional string` + - `parameters: optional unknown` - Details about the pending safety check. + - `strict: optional boolean` - - `agent: optional object { agent_name }` + 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 agent that produced this item. + - `Custom object { name, type, allowed_callers, 3 more }` - - `agent_name: string` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - The canonical name of the agent that produced this item. + - `name: string` - - `created_by: optional string` + The name of the custom tool, used to identify it in tool calls. - The identifier of the actor that created the item. + - `type: "custom"` - - `Reasoning object { id, summary, type, 4 more }` + The type of the custom tool. Always `custom`. - 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). + - `"custom"` - - `id: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The unique identifier of the reasoning content. + The tool invocation context(s). - - `summary: array of object { text, type }` + - `"direct"` - Reasoning summary content. + - `"programmatic"` - - `text: string` + - `defer_loading: optional boolean` - A summary of the reasoning output from the model so far. + Whether this tool should be deferred and discovered via tool search. - - `type: "summary_text"` + - `description: optional string` - The type of the object. Always `summary_text`. + Optional description of the custom tool, used to provide more context. - - `"summary_text"` + - `format: optional object { type } or object { definition, syntax, type }` - - `type: "reasoning"` + The input format for the custom tool. Default is unconstrained text. - The type of the object. Always `reasoning`. + - `Text object { type }` - - `"reasoning"` + Unconstrained free-form text. - - `agent: optional object { agent_name }` + - `type: "text"` - The agent that produced this item. + Unconstrained text format. Always `text`. - - `agent_name: string` + - `"text"` - The canonical name of the agent that produced this item. + - `Grammar object { definition, syntax, type }` - - `content: optional array of object { text, type }` + A grammar defined by the user. - Reasoning text content. + - `definition: string` - - `text: string` + The grammar definition. - The reasoning text from the model. + - `syntax: "lark" or "regex"` - - `type: "reasoning_text"` + The syntax of the grammar definition. One of `lark` or `regex`. - The type of the reasoning text. Always `reasoning_text`. + - `"lark"` - - `"reasoning_text"` + - `"regex"` - - `encrypted_content: optional string` + - `type: "grammar"` - 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. + Grammar format. Always `grammar`. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"grammar"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `type: "namespace"` - - `"in_progress"` + The type of the tool. Always `namespace`. - - `"completed"` + - `"namespace"` - - `"incomplete"` + - `ToolSearch object { type, description, execution, parameters }` - - `Program object { id, call_id, code, 3 more }` + Hosted or BYOT tool search configuration for deferred tools. - - `id: string` + - `type: "tool_search"` - The unique ID of the program item. + The type of the tool. Always `tool_search`. - - `call_id: string` + - `"tool_search"` - The stable call ID of the program item. + - `description: optional string` - - `code: string` + Description shown to the model for a client-executed tool search tool. - The JavaScript source executed by programmatic tool calling. + - `execution: optional "server" or "client"` - - `fingerprint: string` + Whether tool search is executed by the server or by the client. - Opaque program replay fingerprint that must be round-tripped. + - `"server"` - - `type: "program"` + - `"client"` - The type of the item. Always `program`. + - `parameters: optional unknown` - - `"program"` + Parameter schema for a client-executed tool search tool. - - `agent: optional object { agent_name }` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - The agent that produced this item. + 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). - - `agent_name: string` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - The canonical name of the agent that produced this item. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `ProgramOutput object { id, call_id, result, 3 more }` + - `"web_search_preview"` - - `id: string` + - `"web_search_preview_2025_03_11"` - The unique ID of the program output item. + - `search_content_types: optional array of "text" or "image"` - - `call_id: string` + - `"text"` - The call ID of the program item. + - `"image"` - - `result: string` + - `search_context_size: optional "low" or "medium" or "high"` - The result produced by 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. - - `status: "completed" or "incomplete"` + - `"low"` - The terminal status of the program output item. + - `"medium"` - - `"completed"` + - `"high"` - - `"incomplete"` + - `user_location: optional object { type, city, country, 2 more }` - - `type: "program_output"` + The user's location. - The type of the item. Always `program_output`. + - `type: "approximate"` - - `"program_output"` + The type of location approximation. Always `approximate`. - - `agent: optional object { agent_name }` + - `"approximate"` - The agent that produced this item. + - `city: optional string` - - `agent_name: string` + Free text input for the city of the user, e.g. `San Francisco`. - The canonical name of the agent that produced this item. + - `country: optional string` - - `ToolSearchCall object { id, arguments, call_id, 5 more }` + 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 tool search call item. + Free text input for the region of the user, e.g. `California`. - - `arguments: unknown` + - `timezone: optional string` - Arguments used for the tool search call. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `call_id: string` + - `ApplyPatch object { type, allowed_callers }` - The unique ID of the tool search call generated by the model. + Allows the assistant to create, delete, or update files using unified diffs. - - `execution: "server" or "client"` + - `type: "apply_patch"` - Whether tool search was executed by the server or by the client. + The type of the tool. Always `apply_patch`. - - `"server"` + - `"apply_patch"` - - `"client"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `status: "in_progress" or "completed" or "incomplete"` + The tool invocation context(s). - The status of the tool search call item that was recorded. + - `"direct"` - - `"in_progress"` + - `"programmatic"` - - `"completed"` + - `type: "tool_search_output"` - - `"incomplete"` + The item type. Always `tool_search_output`. - - `type: "tool_search_call"` + - `"tool_search_output"` - The type of the item. Always `tool_search_call`. + - `id: optional string` - - `"tool_search_call"` + The unique ID of this tool search output. - `agent: optional object { agent_name }` @@ -188366,21 +188292,11 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` - - The identifier of the actor that created the item. - - - `ToolSearchOutput object { id, call_id, execution, 5 more }` - - - `id: string` - - The unique ID of the tool search output item. - - - `call_id: string` + - `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. @@ -188388,9 +188304,9 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"client"` - - `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 tool search output. - `"in_progress"` @@ -188398,9 +188314,17 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` + - `AdditionalTools object { role, tools, type, 2 more }` + + - `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 tool search. + A list of additional tools made available at this item. - `Function object { name, parameters, strict, 5 more }` @@ -189391,11 +189315,15 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"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"` + + - `id: optional string` + + The unique ID of this additional tools item. - `agent: optional object { agent_name }` @@ -189405,1060 +189333,1830 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` + - `Reasoning object { id, summary, type, 4 more }` - The identifier of the actor that created the item. + A description of the chain of thought used by a reasoning model while generating + a response. Be sure to include these items in your `input` to the Responses API + for subsequent turns of a conversation if you are manually + [managing context](/docs/guides/conversation-state). - - `AdditionalTools object { id, role, tools, 2 more }` + - `id: string` + + The unique identifier of the reasoning content. + + - `summary: array of object { text, type }` + + 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"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `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, agent }` + + 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. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `ImageGenerationCall object { id, result, status, 2 more }` + + An image generation request made by the model. - `id: string` - The unique ID of the additional tools item. + The unique ID of the image generation call. - - `role: "unknown" or "user" or "assistant" or 5 more` + - `result: string` - The role that provided the additional tools. + The generated image encoded in base64. - - `"unknown"` + - `status: "in_progress" or "completed" or "generating" or "failed"` - - `"user"` + The status of the image generation call. - - `"assistant"` + - `"in_progress"` - - `"system"` + - `"completed"` - - `"critic"` + - `"generating"` - - `"discriminator"` + - `"failed"` - - `"developer"` + - `type: "image_generation_call"` - - `"tool"` + The type of the image generation call. Always `image_generation_call`. - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + - `"image_generation_call"` - The additional tool definitions made available at this item. + - `agent: optional object { agent_name }` - - `Function object { name, parameters, strict, 5 more }` + The agent that produced this item. - 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). + - `agent_name: string` - - `name: string` + The canonical name of the agent that produced this item. - The name of the function to call. + - `CodeInterpreterCall object { id, code, container_id, 4 more }` - - `parameters: map[unknown]` + A tool call to run code. - A JSON schema object describing the parameters of the function. + - `id: string` - - `strict: boolean` + The unique ID of the code interpreter tool call. - Whether strict parameter validation is enforced for this function tool. + - `code: string` - - `type: "function"` + The code to run, or null if not available. - The type of the function tool. Always `function`. + - `container_id: string` - - `"function"` + The ID of the container used to run the code. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `outputs: array of object { logs, type } or object { type, url }` - The tool invocation context(s). + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. + + - `Logs object { logs, type }` + + The logs output from the code interpreter. + + - `logs: string` + + The logs output from the code interpreter. + + - `type: "logs"` + + The type of the output. Always `logs`. + + - `"logs"` + + - `Image object { type, url }` + + The image output from the code interpreter. + + - `type: "image"` + + The type of the output. Always `image`. + + - `"image"` + + - `url: string` + + The URL of the image output from the code interpreter. + + - `status: "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"interpreting"` + + - `"failed"` + + - `type: "code_interpreter_call"` + + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `"code_interpreter_call"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `LocalShellCall object { id, action, call_id, 3 more }` + + A tool call to run a command on the local shell. + + - `id: string` + + The unique ID of the local shell call. + + - `action: object { command, env, type, 3 more }` + + Execute a shell command on the server. + + - `command: array of string` + + The command to run. + + - `env: map[string]` + + Environment variables to set for the command. + + - `type: "exec"` + + The type of the local shell action. Always `exec`. + + - `"exec"` + + - `timeout_ms: optional number` + + Optional timeout in milliseconds for the command. + + - `user: optional string` + + Optional user to run the command as. + + - `working_directory: optional string` + + Optional working directory to run the command in. + + - `call_id: string` + + The unique ID of the local shell tool call generated by the model. + + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the local shell call. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "local_shell_call"` + + The type of the local shell call. Always `local_shell_call`. + + - `"local_shell_call"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `LocalShellCallOutput object { id, output, type, 2 more }` + + The output of a local shell tool call. + + - `id: string` + + The unique ID of the local shell tool call generated by the model. + + - `output: string` + + A JSON string of the output of the local shell tool call. + + - `type: "local_shell_call_output"` + + The type of the local shell tool call output. Always `local_shell_call_output`. + + - `"local_shell_call_output"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the item. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `ShellCall object { action, call_id, type, 5 more }` + + A tool representing a request to execute one or more shell commands. + + - `action: object { commands, max_output_length, timeout_ms }` + + The shell commands and limits that describe how to run the tool call. + + - `commands: array of string` + + Ordered shell commands for the execution environment to run. + + - `max_output_length: optional number` + + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + + - `timeout_ms: optional number` + + Maximum wall-clock time in milliseconds to allow the shell commands to run. + + - `call_id: string` + + The unique ID of the shell tool call generated by the model. + + - `type: "shell_call"` + + The type of the item. Always `shell_call`. + + - `"shell_call"` + + - `id: optional string` + + The unique ID of the shell tool call. Populated when this item is returned via API. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. - `"direct"` - - `"programmatic"` + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + + - `environment: optional BetaLocalEnvironment or BetaContainerReference` + + The environment to execute the shell commands in. + + - `BetaLocalEnvironment object { type, skills }` + + - `BetaContainerReference object { container_id, type }` + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `ShellCallOutput object { call_id, output, type, 5 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 BetaResponseFunctionShellCallOutputContent` + + Captured chunks of stdout and stderr output, along with their associated outcomes. + + - `outcome: object { type } or object { exit_code, type }` + + The exit or timeout outcome associated with this shell call. + + - `stderr: string` + + Captured stderr output for the shell call. + + - `stdout: string` + + Captured stdout output for the shell call. + + - `type: "shell_call_output"` + + The type of the item. Always `shell_call_output`. + + - `"shell_call_output"` + + - `id: optional string` + + The unique ID of the shell tool call output. Populated when this item is returned via API. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + + - `max_output_length: optional number` + + The maximum number of UTF-8 characters captured for this shell call's combined output. + + - `status: optional "in_progress" or "completed" or "incomplete"` + + The status of the shell call output. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `ApplyPatchCall object { call_id, operation, status, 4 more }` + + A tool call representing a request to create, delete, or update files using diff patches. + + - `call_id: string` + + The unique ID of the apply patch tool call generated by the model. + + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + + The specific create, delete, or update instruction for the apply_patch tool call. + + - `CreateFile object { diff, path, type }` + + Instruction for creating a new file via the apply_patch tool. + + - `diff: string` + + Unified diff content to apply when creating the file. + + - `path: string` + + Path of the file to create relative to the workspace root. + + - `type: "create_file"` + + The operation type. Always `create_file`. + + - `"create_file"` + + - `DeleteFile object { path, type }` + + Instruction for deleting an existing file via the apply_patch tool. + + - `path: string` + + Path of the file to delete relative to the workspace root. + + - `type: "delete_file"` + + The operation type. Always `delete_file`. + + - `"delete_file"` + + - `UpdateFile object { diff, path, type }` + + Instruction for updating an existing file via the apply_patch tool. + + - `diff: string` + + Unified diff content to apply to the existing file. + + - `path: string` + + Path of the file to update relative to the workspace root. + + - `type: "update_file"` + + The operation type. Always `update_file`. + + - `"update_file"` + + - `status: "in_progress" or "completed"` + + The status of the apply patch tool call. One of `in_progress` or `completed`. + + - `"in_progress"` + + - `"completed"` + + - `type: "apply_patch_call"` + + The type of the item. Always `apply_patch_call`. + + - `"apply_patch_call"` + + - `id: optional string` + + The unique ID of the apply patch tool call. Populated when this item is returned via API. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + + - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` + + The streamed output emitted by an apply patch tool call. + + - `call_id: string` + + The unique ID of the apply patch tool call generated by the model. + + - `status: "completed" or "failed"` + + The status of the apply patch tool call output. One of `completed` or `failed`. + + - `"completed"` + + - `"failed"` + + - `type: "apply_patch_call_output"` + + The type of the item. Always `apply_patch_call_output`. + + - `"apply_patch_call_output"` + + - `id: optional string` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `caller: optional object { type } or object { caller_id, type }` + + The execution context that produced this tool call. + + - `Direct object { type }` + + - `type: "direct"` + + The caller type. Always `direct`. + + - `"direct"` + + - `Program object { caller_id, type }` + + - `caller_id: string` + + The call ID of the program item that produced this tool call. + + - `type: "program"` + + The caller type. Always `program`. + + - `"program"` + + - `output: optional string` + + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + + - `McpListTools object { id, server_label, tools, 3 more }` + + A list of tools available on an MCP server. + + - `id: string` + + The unique ID of the list. + + - `server_label: string` + + The label of the MCP server. + + - `tools: array of object { input_schema, name, annotations, description }` + + The tools available on the server. + + - `input_schema: unknown` + + The JSON schema describing the tool's input. + + - `name: string` + + The name of the tool. + + - `annotations: optional unknown` + + Additional annotations about the tool. + + - `description: optional string` + + The description of the tool. + + - `type: "mcp_list_tools"` + + The type of the item. Always `mcp_list_tools`. + + - `"mcp_list_tools"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `error: optional string` + + Error message if the server could not list tools. + + - `McpApprovalRequest object { id, arguments, name, 3 more }` + + A request for human approval of a tool invocation. + + - `id: string` + + The unique ID of the approval request. + + - `arguments: string` + + A JSON string of arguments for the tool. + + - `name: string` + + The name of the tool to run. + + - `server_label: string` + + The label of the MCP server making the request. + + - `type: "mcp_approval_request"` + + The type of the item. Always `mcp_approval_request`. + + - `"mcp_approval_request"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` + + A response to an MCP approval request. + + - `approval_request_id: string` + + The ID of the approval request being answered. + + - `approve: boolean` + + Whether the request was approved. + + - `type: "mcp_approval_response"` + + The type of the item. Always `mcp_approval_response`. + + - `"mcp_approval_response"` + + - `id: optional string` + + The unique ID of the approval response + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `reason: optional string` + + Optional reason for the decision. + + - `McpCall object { id, arguments, name, 7 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"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `approval_request_id: optional string` + + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + + - `error: optional string` + + The error from the tool call, if any. + + - `output: optional string` + + The output from the tool call. + + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"calling"` + + - `"failed"` + + - `CustomToolCallOutput object { call_id, output, type, 3 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. + + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + + 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 BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + + Text, image, or file output of the custom tool call. + + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](/docs/guides/vision). + + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + + A file input to the model. - - `defer_loading: optional boolean` + - `type: "custom_tool_call_output"` - Whether this function is deferred and loaded via tool search. + The type of the custom tool call output. Always `custom_tool_call_output`. - - `description: optional string` + - `"custom_tool_call_output"` - A description of the function. Used by the model to determine whether or not to call the function. + - `id: optional string` - - `output_schema: optional map[unknown]` + The unique ID of the custom tool call output in the OpenAI platform. - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `agent: optional object { agent_name }` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + The agent that produced this item. - 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). + - `agent_name: string` - - `type: "file_search"` + The canonical name of the agent that produced this item. - The type of the file search tool. Always `file_search`. + - `caller: optional object { type } or object { caller_id, type }` - - `"file_search"` + The execution context that produced this tool call. - - `vector_store_ids: array of string` + - `Direct object { type }` - The IDs of the vector stores to search. + - `type: "direct"` - - `filters: optional object { key, type, value } or object { filters, type }` + The caller type. Always `direct`. - A filter to apply. + - `"direct"` - - `ComparisonFilter object { key, type, value }` + - `Program object { caller_id, type }` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `caller_id: string` - - `key: string` + The call ID of the program item that produced this tool call. - The key to compare against the value. + - `type: "program"` - - `type: "eq" or "ne" or "gt" or 5 more` + The caller type. Always `program`. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"program"` - - `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 + - `CustomToolCall object { call_id, input, name, 5 more }` - - `"eq"` + A call to a custom tool created by the model. - - `"ne"` + - `call_id: string` - - `"gt"` + An identifier used to map this custom tool call to a tool call output. - - `"gte"` + - `input: string` - - `"lt"` + The input for the custom tool call generated by the model. - - `"lte"` + - `name: string` - - `"in"` + The name of the custom tool being called. - - `"nin"` + - `type: "custom_tool_call"` - - `value: string or number or boolean or array of string or number` + The type of the custom tool call. Always `custom_tool_call`. - The value to compare against the attribute key; supports string, number, or boolean types. + - `"custom_tool_call"` - - `string` + - `id: optional string` - - `number` + The unique ID of the custom tool call in the OpenAI platform. - - `boolean` + - `agent: optional object { agent_name }` - - `array of string or number` + The agent that produced this item. - - `string` + - `agent_name: string` - - `number` + The canonical name of the agent that produced this item. - - `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. - - `filters: array of object { key, type, value } or unknown` + - `Direct object { type }` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `type: "direct"` - - `ComparisonFilter object { key, type, value }` + - `"direct"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `Program object { caller_id, type }` - - `key: string` + - `caller_id: string` - The key to compare against the value. + The call ID of the program item that produced this tool call. - - `type: "eq" or "ne" or "gt" or 5 more` + - `type: "program"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"program"` - - `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 + - `namespace: optional string` - - `"eq"` + The namespace of the custom tool being called. - - `"ne"` + - `CompactionTrigger object { type, agent }` - - `"gt"` + Compacts the current context. Must be the final input item. - - `"gte"` + - `type: "compaction_trigger"` - - `"lt"` + The type of the item. Always `compaction_trigger`. - - `"lte"` + - `"compaction_trigger"` - - `"in"` + - `agent: optional object { agent_name }` - - `"nin"` + The agent that produced this item. - - `value: string or number or boolean or array of string or number` + - `agent_name: string` - The value to compare against the attribute key; supports string, number, or boolean types. + The canonical name of the agent that produced this item. - - `string` + - `ItemReference object { id, agent, type }` - - `number` + An internal identifier for an item to reference. - - `boolean` + - `id: string` - - `array of string or number` + The ID of the item to reference. - - `string` + - `agent: optional object { agent_name }` - - `number` + The agent that produced this item. - - `unknown` + - `agent_name: string` - - `type: "and" or "or"` + The canonical name of the agent that produced this item. - Type of operation: `and` or `or`. + - `type: optional "item_reference"` - - `"and"` + The type of item to reference. Always `item_reference`. - - `"or"` + - `"item_reference"` - - `max_num_results: optional number` + - `Program object { id, call_id, code, 3 more }` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `id: string` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + The unique ID of this program item. - Ranking options for search. + - `call_id: string` - - `hybrid_search: optional object { embedding_weight, text_weight }` + The stable call ID of the program item. - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `code: string` - - `embedding_weight: number` + The JavaScript source executed by programmatic tool calling. - The weight of the embedding in the reciprocal ranking fusion. + - `fingerprint: string` - - `text_weight: number` + Opaque program replay fingerprint that must be round-tripped. - The weight of the text in the reciprocal ranking fusion. + - `type: "program"` - - `ranker: optional "auto" or "default-2024-11-15"` + The item type. Always `program`. - The ranker to use for the file search. + - `"program"` - - `"auto"` + - `agent: optional object { agent_name }` - - `"default-2024-11-15"` + The agent that produced this item. - - `score_threshold: optional number` + - `agent_name: 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 canonical name of the agent that produced this item. - - `Computer object { type }` + - `ProgramOutput object { id, call_id, result, 3 more }` - 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 unique ID of this program output item. - The type of the computer tool. Always `computer`. + - `call_id: string` - - `"computer"` + The call ID of the program item. - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `result: string` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + The result produced by the program item. - - `display_height: number` + - `status: "completed" or "incomplete"` - The height of the computer display. + The terminal status of the program output. - - `display_width: number` + - `"completed"` - The width of the computer display. + - `"incomplete"` - - `environment: "windows" or "mac" or "linux" or 2 more` + - `type: "program_output"` - The type of computer environment to control. + The item type. Always `program_output`. - - `"windows"` + - `"program_output"` - - `"mac"` + - `agent: optional object { agent_name }` - - `"linux"` + The agent that produced this item. - - `"ubuntu"` + - `agent_name: string` - - `"browser"` + The canonical name of the agent that produced this item. - - `type: "computer_use_preview"` + - `response_id: string` - The type of the computer use tool. Always `computer_use_preview`. + The ID of the active response that should receive the input. - - `"computer_use_preview"` + - `type: "response.inject"` - - `WebSearch object { type, filters, search_context_size, user_location }` + The event discriminator. Always `response.inject`. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + - `"response.inject"` - - `type: "web_search" or "web_search_2025_08_26"` +### Beta Responses Server Event - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. +- `BetaResponsesServerEvent = BetaResponseAudioDeltaEvent or BetaResponseAudioDoneEvent or BetaResponseAudioTranscriptDeltaEvent or 52 more` - - `"web_search"` + Server events emitted by the Responses WebSocket server. - - `"web_search_2025_08_26"` + - `BetaResponseAudioDeltaEvent object { delta, sequence_number, type, agent }` - - `filters: optional object { allowed_domains }` + Emitted when there is a partial audio response. - Filters for the search. + - `delta: string` - - `allowed_domains: optional array of string` + A chunk of Base64 encoded response audio bytes. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `sequence_number: number` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + A sequence number for this chunk of the stream response. - - `search_context_size: optional "low" or "medium" or "high"` + - `type: "response.audio.delta"` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The type of the event. Always `response.audio.delta`. - - `"low"` + - `"response.audio.delta"` - - `"medium"` + - `agent: optional object { agent_name }` - - `"high"` + The agent that owns this multi-agent streaming event. - - `user_location: optional object { city, country, region, 2 more }` + - `agent_name: string` - The approximate location of the user. + The canonical name of the agent that produced this item. - - `city: optional string` + - `BetaResponseAudioDoneEvent object { sequence_number, type, agent }` - Free text input for the city of the user, e.g. `San Francisco`. + Emitted when the audio response is complete. - - `country: optional string` + - `sequence_number: number` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The sequence number of the delta. - - `region: optional string` + - `type: "response.audio.done"` - Free text input for the region of the user, e.g. `California`. + The type of the event. Always `response.audio.done`. - - `timezone: optional string` + - `"response.audio.done"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `agent: optional object { agent_name }` - - `type: optional "approximate"` + The agent that owns this multi-agent streaming event. - The type of location approximation. Always `approximate`. + - `agent_name: string` - - `"approximate"` + The canonical name of the agent that produced this item. - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `BetaResponseAudioTranscriptDeltaEvent object { delta, sequence_number, type, agent }` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + Emitted when there is a partial transcript of audio. - - `server_label: string` + - `delta: string` - A label for this MCP server, used to identify it in tool calls. + The partial transcript of the audio response. - - `type: "mcp"` + - `sequence_number: number` - The type of the MCP tool. Always `mcp`. + The sequence number of this event. - - `"mcp"` + - `type: "response.audio.transcript.delta"` - - `allowed_callers: optional array of "direct" or "programmatic"` + The type of the event. Always `response.audio.transcript.delta`. - The tool invocation context(s). + - `"response.audio.transcript.delta"` - - `"direct"` + - `agent: optional object { agent_name }` - - `"programmatic"` + The agent that owns this multi-agent streaming event. - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `agent_name: string` - List of allowed tool names or a filter object. + The canonical name of the agent that produced this item. - - `McpAllowedTools = array of string` + - `BetaResponseAudioTranscriptDoneEvent object { sequence_number, type, agent }` - A string array of allowed tool names + Emitted when the full audio transcript is completed. - - `McpToolFilter object { read_only, tool_names }` + - `sequence_number: number` - A filter object to specify which tools are allowed. + The sequence number of this event. - - `read_only: optional boolean` + - `type: "response.audio.transcript.done"` - 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 event. Always `response.audio.transcript.done`. - - `tool_names: optional array of string` + - `"response.audio.transcript.done"` - List of allowed tool names. + - `agent: optional object { agent_name }` - - `authorization: optional string` + The agent that owns this multi-agent streaming event. - 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. + - `agent_name: string` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + The canonical name of the agent that produced this item. - 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). + - `BetaResponseCodeInterpreterCallCodeDeltaEvent object { delta, item_id, output_index, 3 more }` - Currently supported `connector_id` values are: + Emitted when a partial code snippet is streamed by the code interpreter. - - 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` + - `delta: string` - - `"connector_dropbox"` + The partial code snippet being streamed by the code interpreter. - - `"connector_gmail"` + - `item_id: string` - - `"connector_googlecalendar"` + The unique identifier of the code interpreter tool call item. - - `"connector_googledrive"` + - `output_index: number` - - `"connector_microsoftteams"` + The index of the output item in the response for which the code is being streamed. - - `"connector_outlookcalendar"` + - `sequence_number: number` - - `"connector_outlookemail"` + The sequence number of this event, used to order streaming events. - - `"connector_sharepoint"` + - `type: "response.code_interpreter_call_code.delta"` - - `defer_loading: optional boolean` + The type of the event. Always `response.code_interpreter_call_code.delta`. - Whether this MCP tool is deferred and discovered via tool search. + - `"response.code_interpreter_call_code.delta"` - - `headers: optional map[string]` + - `agent: optional object { agent_name }` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + The agent that owns this multi-agent streaming event. - - `require_approval: optional object { always, never } or "always" or "never"` + - `agent_name: string` - Specify which of the MCP server's tools require approval. + The canonical name of the agent that produced this item. - - `McpToolApprovalFilter object { always, never }` + - `BetaResponseCodeInterpreterCallCodeDoneEvent object { code, item_id, output_index, 3 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. + Emitted when the code snippet is finalized by the code interpreter. - - `always: optional object { read_only, tool_names }` + - `code: string` - A filter object to specify which tools are allowed. + The final code snippet output by the code interpreter. - - `read_only: optional boolean` + - `item_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 identifier of the code interpreter tool call item. - - `tool_names: optional array of string` + - `output_index: number` - List of allowed tool names. + The index of the output item in the response for which the code is finalized. - - `never: optional object { read_only, tool_names }` + - `sequence_number: number` - A filter object to specify which tools are allowed. + The sequence number of this event, used to order streaming events. - - `read_only: optional boolean` + - `type: "response.code_interpreter_call_code.done"` - 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 event. Always `response.code_interpreter_call_code.done`. - - `tool_names: optional array of string` + - `"response.code_interpreter_call_code.done"` - List of allowed tool names. + - `agent: optional object { agent_name }` - - `McpToolApprovalSetting = "always" or "never"` + The agent that owns this multi-agent streaming event. - 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. + - `agent_name: string` - - `"always"` + The canonical name of the agent that produced this item. - - `"never"` + - `BetaResponseCodeInterpreterCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - - `server_description: optional string` + Emitted when the code interpreter call is completed. - Optional description of the MCP server, used to provide more context. + - `item_id: string` - - `server_url: optional string` + The unique identifier of the code interpreter tool call item. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `output_index: number` - - `tunnel_id: optional string` + The index of the output item in the response for which the code interpreter call is completed. - 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. + - `sequence_number: number` - - `CodeInterpreter object { container, type, allowed_callers }` + The sequence number of this event, used to order streaming events. - A tool that runs Python code to help generate a response to a prompt. + - `type: "response.code_interpreter_call.completed"` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + The type of the event. Always `response.code_interpreter_call.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. + - `"response.code_interpreter_call.completed"` - - `string` + - `agent: optional object { agent_name }` - The container ID. + The agent that owns this multi-agent streaming event. - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `agent_name: string` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + The canonical name of the agent that produced this item. - - `type: "auto"` + - `BetaResponseCodeInterpreterCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` - Always `auto`. + Emitted when a code interpreter call is in progress. - - `"auto"` + - `item_id: string` - - `file_ids: optional array of string` + The unique identifier of the code interpreter tool call item. - An optional list of uploaded files to make available to your code. + - `output_index: number` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + The index of the output item in the response for which the code interpreter call is in progress. - The memory limit for the code interpreter container. + - `sequence_number: number` - - `"1g"` + The sequence number of this event, used to order streaming events. - - `"4g"` + - `type: "response.code_interpreter_call.in_progress"` - - `"16g"` + The type of the event. Always `response.code_interpreter_call.in_progress`. - - `"64g"` + - `"response.code_interpreter_call.in_progress"` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `agent: optional object { agent_name }` - Network access policy for the container. + The agent that owns this multi-agent streaming event. - - `BetaContainerNetworkPolicyDisabled object { type }` + - `agent_name: string` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + The canonical name of the agent that produced this item. - - `type: "code_interpreter"` + - `BetaResponseCodeInterpreterCallInterpretingEvent object { item_id, output_index, sequence_number, 2 more }` - The type of the code interpreter tool. Always `code_interpreter`. + Emitted when the code interpreter is actively interpreting the code snippet. - - `"code_interpreter"` + - `item_id: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The unique identifier of the code interpreter tool call item. - The tool invocation context(s). + - `output_index: number` - - `"direct"` + The index of the output item in the response for which the code interpreter is interpreting code. - - `"programmatic"` + - `sequence_number: number` - - `ProgrammaticToolCalling object { type }` + The sequence number of this event, used to order streaming events. - - `type: "programmatic_tool_calling"` + - `type: "response.code_interpreter_call.interpreting"` - The type of the tool. Always `programmatic_tool_calling`. + The type of the event. Always `response.code_interpreter_call.interpreting`. - - `"programmatic_tool_calling"` + - `"response.code_interpreter_call.interpreting"` - - `ImageGeneration object { type, action, background, 9 more }` + - `agent: optional object { agent_name }` - A tool that generates images using the GPT image models. + The agent that owns this multi-agent streaming event. - - `type: "image_generation"` + - `agent_name: string` - The type of the image generation tool. Always `image_generation`. + The canonical name of the agent that produced this item. - - `"image_generation"` + - `BetaResponseCompletedEvent object { response, sequence_number, type, agent }` - - `action: optional "generate" or "edit" or "auto"` + Emitted when the model response is complete. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `response: BetaResponse` - - `"generate"` + Properties of the completed response. - - `"edit"` + - `id: string` - - `"auto"` + Unique identifier for this Response. - - `background: optional "transparent" or "opaque" or "auto"` + - `created_at: number` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + Unix timestamp (in seconds) of when this Response was created. - - `"transparent"` + - `error: BetaResponseError` - - `"opaque"` + An error object returned when the model fails to generate a Response. - - `"auto"` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt" or 17 more` - - `input_fidelity: optional "high" or "low"` + The error code for the response. - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + - `"server_error"` - - `"high"` + - `"rate_limit_exceeded"` - - `"low"` + - `"invalid_prompt"` - - `input_image_mask: optional object { file_id, image_url }` + - `"data_residency_mismatch"` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `"bio_policy"` - - `file_id: optional string` + - `"vector_store_timeout"` - File ID for the mask image. + - `"invalid_image"` - - `image_url: optional string` + - `"invalid_image_format"` - Base64-encoded mask image. + - `"invalid_base64_image"` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"invalid_image_url"` - The image generation model to use. Default: `gpt-image-1`. + - `"image_too_large"` - - `string` + - `"image_too_small"` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `"image_parse_error"` - The image generation model to use. Default: `gpt-image-1`. + - `"image_content_policy_violation"` - - `"gpt-image-1"` + - `"invalid_image_mode"` - - `"gpt-image-1-mini"` + - `"image_file_too_large"` - - `"gpt-image-1.5"` + - `"unsupported_image_media_type"` - - `moderation: optional "auto" or "low"` + - `"empty_image_file"` - Moderation level for the generated image. Default: `auto`. + - `"failed_to_download_image"` - - `"auto"` + - `"image_file_not_found"` - - `"low"` + - `message: string` - - `output_compression: optional number` + A human-readable description of the error. - Compression level for the output image. Default: 100. + - `incomplete_details: object { reason }` - - `output_format: optional "png" or "webp" or "jpeg"` + Details about why the response is incomplete. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `reason: optional "max_output_tokens" or "content_filter"` - - `"png"` + The reason why the response is incomplete. - - `"webp"` + - `"max_output_tokens"` - - `"jpeg"` + - `"content_filter"` - - `partial_images: optional number` + - `instructions: string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + A system (or developer) message inserted into the model's context. - - `quality: optional "low" or "medium" or "high" or "auto"` + 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. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `string` - - `"low"` + A text input to the model, equivalent to a text input with the + `developer` role. - - `"medium"` + - `InputItemList = array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - - `"high"` + A list of one or many input items to the model, containing + different content types. - - `"auto"` + - `BetaEasyInputMessage object { content, role, phase, type }` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + 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 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`. + - `content: string or BetaResponseInputMessageContentList` - - `string` + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `TextInput = 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`. + A text input to the model. - - `"1024x1024"` + - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` - - `"1024x1536"` + A list of one or many input items to the model, containing different content + types. - - `"1536x1024"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `"auto"` + A text input to the model. - - `LocalShell object { type }` + - `text: string` - A tool that allows the model to execute shell commands in a local environment. + The text input to the model. - - `type: "local_shell"` + - `type: "input_text"` - The type of the local shell tool. Always `local_shell`. + The type of the input item. Always `input_text`. - - `"local_shell"` + - `"input_text"` - - `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"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - The tool invocation context(s). + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"direct"` + - `detail: "low" or "high" or "auto" or "original"` - - `"programmatic"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `"low"` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `"high"` - - `BetaLocalEnvironment object { type, skills }` + - `"auto"` - - `BetaContainerReference object { container_id, type }` + - `"original"` - - `Custom object { name, type, allowed_callers, 3 more }` + - `type: "input_image"` - 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 input item. Always `input_image`. - - `name: string` + - `"input_image"` - The name of the custom tool, used to identify it in tool calls. + - `file_id: optional string` - - `type: "custom"` + The ID of the file to be sent to the model. - The type of the custom tool. Always `custom`. + - `image_url: optional string` - - `"custom"` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `prompt_cache_breakpoint: optional object { mode }` - The tool invocation context(s). + 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. - - `"direct"` + - `mode: "explicit"` - - `"programmatic"` + The breakpoint mode. Always `explicit`. - - `defer_loading: optional boolean` + - `"explicit"` - Whether this tool should be deferred and discovered via tool search. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `description: optional string` + A file input to the model. - Optional description of the custom tool, used to provide more context. + - `type: "input_file"` - - `format: optional object { type } or object { definition, syntax, type }` + The type of the input item. Always `input_file`. - The input format for the custom tool. Default is unconstrained text. + - `"input_file"` - - `Text object { type }` + - `detail: optional "auto" or "low" or "high"` - Unconstrained free-form text. + 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: "text"` + - `"auto"` - Unconstrained text format. Always `text`. + - `"low"` - - `"text"` + - `"high"` - - `Grammar object { definition, syntax, type }` + - `file_data: optional string` - A grammar defined by the user. + The content of the file to be sent to the model. - - `definition: string` + - `file_id: optional string` - The grammar definition. + The ID of the file to be sent to the model. - - `syntax: "lark" or "regex"` + - `file_url: optional string` - The syntax of the grammar definition. One of `lark` or `regex`. + The URL of the file to be sent to the model. - - `"lark"` + - `filename: optional string` - - `"regex"` + The name of the file to be sent to the model. - - `type: "grammar"` + - `prompt_cache_breakpoint: optional object { mode }` - Grammar format. Always `grammar`. + 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. - - `"grammar"` + - `mode: "explicit"` - - `Namespace object { description, name, tools, type }` + The breakpoint mode. Always `explicit`. - Groups function/custom tools under a shared namespace. + - `"explicit"` - - `description: string` + - `role: "user" or "assistant" or "system" or "developer"` - A description of the namespace shown to the model. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `name: string` + - `"user"` - The namespace name used in tool calls (for example, `crm`). + - `"assistant"` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `"system"` - The function/custom tools available inside this namespace. + - `"developer"` - - `Function object { name, type, allowed_callers, 5 more }` + - `phase: optional "commentary" or "final_answer"` - - `name: 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. - - `type: "function"` + - `"commentary"` - - `"function"` + - `"final_answer"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `type: optional "message"` - The tool invocation context(s). + The type of the message input. Always `message`. - - `"direct"` + - `"message"` - - `"programmatic"` + - `Message object { content, role, agent, 2 more }` - - `defer_loading: optional boolean` + 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. - Whether this function should be deferred and discovered via tool search. + - `content: BetaResponseInputMessageContentList` - - `description: optional string` + A list of one or many input items to the model, containing different content + types. - - `output_schema: optional map[unknown]` + - `role: "user" or "system" or "developer"` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + The role of the message input. One of `user`, `system`, or `developer`. - - `parameters: optional unknown` + - `"user"` - - `strict: optional boolean` + - `"system"` - 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. + - `"developer"` - - `Custom object { name, type, allowed_callers, 3 more }` + - `agent: optional object { agent_name }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + The agent that produced this item. - - `name: string` + - `agent_name: string` - The name of the custom tool, used to identify it in tool calls. + The canonical name of the agent that produced this item. - - `type: "custom"` + - `status: optional "in_progress" or "completed" or "incomplete"` - The type of the custom tool. Always `custom`. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"custom"` + - `"in_progress"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"completed"` - The tool invocation context(s). + - `"incomplete"` - - `"direct"` + - `type: optional "message"` - - `"programmatic"` + The type of the message input. Always set to `message`. - - `defer_loading: optional boolean` + - `"message"` - Whether this tool should be deferred and discovered via tool search. + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - - `description: optional string` + An output message from the model. - Optional description of the custom tool, used to provide more context. + - `id: string` - - `format: optional object { type } or object { definition, syntax, type }` + The unique ID of the output message. - The input format for the custom tool. Default is unconstrained text. + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - - `Text object { type }` + The content of the output message. - Unconstrained free-form text. + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - - `type: "text"` + A text output from the model. - Unconstrained text format. Always `text`. + - `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 }` - - `"text"` + The annotations of the text output. - - `Grammar object { definition, syntax, type }` + - `FileCitation object { file_id, filename, index, type }` - A grammar defined by the user. + A citation to a file. - - `definition: string` + - `file_id: string` - The grammar definition. + The ID of the file. - - `syntax: "lark" or "regex"` + - `filename: string` - The syntax of the grammar definition. One of `lark` or `regex`. + The filename of the file cited. - - `"lark"` + - `index: number` - - `"regex"` + The index of the file in the list of files. - - `type: "grammar"` + - `type: "file_citation"` - Grammar format. Always `grammar`. + The type of the file citation. Always `file_citation`. - - `"grammar"` + - `"file_citation"` - - `type: "namespace"` + - `URLCitation object { end_index, start_index, title, 2 more }` - The type of the tool. Always `namespace`. + A citation for a web resource used to generate a model response. - - `"namespace"` + - `end_index: number` - - `ToolSearch object { type, description, execution, parameters }` + The index of the last character of the URL citation in the message. - Hosted or BYOT tool search configuration for deferred tools. + - `start_index: number` - - `type: "tool_search"` + The index of the first character of the URL citation in the message. - The type of the tool. Always `tool_search`. + - `title: string` - - `"tool_search"` + The title of the web resource. - - `description: optional string` + - `type: "url_citation"` - Description shown to the model for a client-executed tool search tool. + The type of the URL citation. Always `url_citation`. - - `execution: optional "server" or "client"` + - `"url_citation"` - Whether tool search is executed by the server or by the client. + - `url: string` - - `"server"` + The URL of the web resource. - - `"client"` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - - `parameters: optional unknown` + A citation for a container file used to generate a model response. - Parameter schema for a client-executed tool search tool. + - `container_id: string` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + The ID of the container file. - 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). + - `end_index: number` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + The index of the last character of the container file citation in the message. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `file_id: string` - - `"web_search_preview"` + The ID of the file. - - `"web_search_preview_2025_03_11"` + - `filename: string` - - `search_content_types: optional array of "text" or "image"` + The filename of the container file cited. - - `"text"` + - `start_index: number` - - `"image"` + The index of the first character of the container file citation in the message. - - `search_context_size: optional "low" or "medium" or "high"` + - `type: "container_file_citation"` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The type of the container file citation. Always `container_file_citation`. - - `"low"` + - `"container_file_citation"` - - `"medium"` + - `FilePath object { file_id, index, type }` - - `"high"` + A path to a file. - - `user_location: optional object { type, city, country, 2 more }` + - `file_id: string` - The user's location. + The ID of the file. - - `type: "approximate"` + - `index: number` - The type of location approximation. Always `approximate`. + The index of the file in the list of files. - - `"approximate"` + - `type: "file_path"` - - `city: optional string` + The type of the file path. Always `file_path`. - Free text input for the city of the user, e.g. `San Francisco`. + - `"file_path"` - - `country: optional string` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `token: string` - - `region: optional string` + - `bytes: array of number` - Free text input for the region of the user, e.g. `California`. + - `logprob: number` - - `timezone: optional string` + - `top_logprobs: array of object { token, bytes, logprob }` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `token: string` - - `ApplyPatch object { type, allowed_callers }` + - `bytes: array of number` - Allows the assistant to create, delete, or update files using unified diffs. + - `logprob: number` - - `type: "apply_patch"` + - `text: string` - The type of the tool. Always `apply_patch`. + The text output from the model. - - `"apply_patch"` + - `type: "output_text"` - - `allowed_callers: optional array of "direct" or "programmatic"` + The type of the output text. Always `output_text`. - The tool invocation context(s). + - `"output_text"` - - `"direct"` + - `BetaResponseOutputRefusal object { refusal, type }` - - `"programmatic"` + A refusal from the model. - - `type: "additional_tools"` + - `refusal: string` - The type of the item. Always `additional_tools`. + The refusal explanation from the model. - - `"additional_tools"` + - `type: "refusal"` - - `agent: optional object { agent_name }` + The type of the refusal. Always `refusal`. - The agent that produced this item. + - `"refusal"` - - `agent_name: string` + - `role: "assistant"` - The canonical name of the agent that produced this item. + The role of the output message. Always `assistant`. - - `Compaction object { id, encrypted_content, type, 2 more }` + - `"assistant"` - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + - `status: "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 ID of the compaction item. + - `"in_progress"` - - `encrypted_content: string` + - `"completed"` - The encrypted content that was produced by compaction. + - `"incomplete"` - - `type: "compaction"` + - `type: "message"` - The type of the item. Always `compaction`. + The type of the output message. Always `message`. - - `"compaction"` + - `"message"` - `agent: optional object { agent_name }` @@ -190468,39 +191166,49 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `created_by: optional string` + - `phase: optional "commentary" or "final_answer"` - The identifier of the actor that created the item. + 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. - - `ImageGenerationCall object { id, result, status, 2 more }` + - `"commentary"` - An image generation request made by the model. + - `"final_answer"` + + - `FileSearchCall object { id, queries, status, 3 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 image generation call. + The unique ID of the file search tool call. - - `result: string` + - `queries: array of string` - The generated image encoded in base64. + The queries used to search for files. - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `status: "in_progress" or "searching" or "completed" or 2 more` - The status of the image generation call. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - `"in_progress"` + - `"searching"` + - `"completed"` - - `"generating"` + - `"incomplete"` - `"failed"` - - `type: "image_generation_call"` + - `type: "file_search_call"` - The type of the image generation call. Always `image_generation_call`. + The type of the file search tool call. Always `file_search_call`. - - `"image_generation_call"` + - `"file_search_call"` - `agent: optional object { agent_name }` @@ -190510,58 +191218,73 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `CodeInterpreterCall object { id, code, container_id, 4 more }` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - A tool call to run code. + The results of the file search tool call. - - `id: string` + - `attributes: optional map[string or number or boolean]` - The unique ID of the code interpreter tool call. + 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: string` + - `string` - The code to run, or null if not available. + - `number` - - `container_id: string` + - `boolean` - The ID of the container used to run the code. + - `file_id: optional string` - - `outputs: array of object { logs, type } or object { type, url }` + The unique ID of the file. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `filename: optional string` - - `Logs object { logs, type }` + The name of the file. - The logs output from the code interpreter. + - `score: optional number` - - `logs: string` + The relevance score of the file - a value between 0 and 1. - The logs output from the code interpreter. + - `text: optional string` - - `type: "logs"` + The text that was retrieved from the file. - The type of the output. Always `logs`. + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - - `"logs"` + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - - `Image object { type, url }` + - `id: string` - The image output from the code interpreter. + The unique ID of the computer call. - - `type: "image"` + - `call_id: string` - The type of the output. Always `image`. + An identifier used when responding to the tool call with output. - - `"image"` + - `pending_safety_checks: array of object { id, code, message }` - - `url: string` + The pending safety checks for the computer call. - The URL of the image output from the code interpreter. + - `id: string` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + The ID of the pending safety check. - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `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"` @@ -190569,301 +191292,308 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `"interpreting"` + - `type: "computer_call"` - - `"failed"` + The type of the computer call. Always `computer_call`. - - `type: "code_interpreter_call"` + - `"computer_call"` - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `action: optional BetaComputerAction` - - `"code_interpreter_call"` + A click action. - - `agent: optional object { agent_name }` + - `Click object { button, type, x, 2 more }` - The agent that produced this item. + A click action. - - `agent_name: string` + - `button: "left" or "right" or "wheel" or 2 more` - The canonical name of the agent that produced this item. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `LocalShellCall object { id, action, call_id, 3 more }` + - `"left"` - A tool call to run a command on the local shell. + - `"right"` - - `id: string` + - `"wheel"` - The unique ID of the local shell call. + - `"back"` - - `action: object { command, env, type, 3 more }` + - `"forward"` - Execute a shell command on the server. + - `type: "click"` - - `command: array of string` + Specifies the event type. For a click action, this property is always `click`. - The command to run. + - `"click"` - - `env: map[string]` + - `x: number` - Environment variables to set for the command. + The x-coordinate where the click occurred. - - `type: "exec"` + - `y: number` - The type of the local shell action. Always `exec`. + The y-coordinate where the click occurred. - - `"exec"` + - `keys: optional array of string` - - `timeout_ms: optional number` + The keys being held while clicking. - Optional timeout in milliseconds for the command. + - `DoubleClick object { keys, type, x, y }` - - `user: optional string` + A double click action. - Optional user to run the command as. + - `keys: array of string` - - `working_directory: optional string` + The keys being held while double-clicking. - Optional working directory to run the command in. + - `type: "double_click"` - - `call_id: string` + Specifies the event type. For a double click action, this property is always set to `double_click`. - The unique ID of the local shell tool call generated by the model. + - `"double_click"` - - `status: "in_progress" or "completed" or "incomplete"` + - `x: number` - The status of the local shell call. + The x-coordinate where the double click occurred. - - `"in_progress"` + - `y: number` - - `"completed"` + The y-coordinate where the double click occurred. - - `"incomplete"` + - `Drag object { path, type, keys }` - - `type: "local_shell_call"` + A drag action. - The type of the local shell call. Always `local_shell_call`. + - `path: array of object { x, y }` - - `"local_shell_call"` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `agent: optional object { agent_name }` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - The agent that produced this item. + - `x: number` - - `agent_name: string` + The x-coordinate. - The canonical name of the agent that produced this item. + - `y: number` - - `LocalShellCallOutput object { id, output, type, 2 more }` + The y-coordinate. - The output of a local shell tool call. + - `type: "drag"` - - `id: string` + Specifies the event type. For a drag action, this property is always set to `drag`. - The unique ID of the local shell tool call generated by the model. + - `"drag"` - - `output: string` + - `keys: optional array of string` - A JSON string of the output of the local shell tool call. + The keys being held while dragging the mouse. - - `type: "local_shell_call_output"` + - `Keypress object { keys, type }` - The type of the local shell tool call output. Always `local_shell_call_output`. + A collection of keypresses the model would like to perform. - - `"local_shell_call_output"` + - `keys: array of string` - - `agent: optional object { agent_name }` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - The agent that produced this item. + - `type: "keypress"` - - `agent_name: string` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - The canonical name of the agent that produced this item. + - `"keypress"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `Move object { type, x, y, keys }` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + A mouse move action. - - `"in_progress"` + - `type: "move"` - - `"completed"` + Specifies the event type. For a move action, this property is always set to `move`. - - `"incomplete"` + - `"move"` - - `ShellCall object { id, action, call_id, 6 more }` + - `x: number` - A tool call that executes one or more shell commands in a managed environment. + The x-coordinate to move to. - - `id: string` + - `y: number` - The unique ID of the shell tool call. Populated when this item is returned via API. + The y-coordinate to move to. - - `action: object { commands, max_output_length, timeout_ms }` + - `keys: optional array of string` - The shell commands and limits that describe how to run the tool call. + The keys being held while moving the mouse. - - `commands: array of string` + - `Screenshot object { type }` - - `max_output_length: number` + A screenshot action. - Optional maximum number of characters to return from each command. + - `type: "screenshot"` - - `timeout_ms: number` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - Optional timeout in milliseconds for the commands. + - `"screenshot"` - - `call_id: string` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - The unique ID of the shell tool call generated by the model. + A scroll action. - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + - `scroll_x: number` - Represents the use of a local environment to perform shell actions. + The horizontal scroll distance. - - `BetaResponseLocalEnvironment object { type }` + - `scroll_y: number` - Represents the use of a local environment to perform shell actions. + The vertical scroll distance. - - `type: "local"` + - `type: "scroll"` - The environment type. Always `local`. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `"local"` + - `"scroll"` - - `BetaResponseContainerReference object { container_id, type }` + - `x: number` - Represents a container created with /v1/containers. + The x-coordinate where the scroll occurred. - - `container_id: string` + - `y: number` - - `type: "container_reference"` + The y-coordinate where the scroll occurred. - The environment type. Always `container_reference`. + - `keys: optional array of string` - - `"container_reference"` + The keys being held while scrolling. - - `status: "in_progress" or "completed" or "incomplete"` + - `Type object { text, type }` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + An action to type in text. - - `"in_progress"` + - `text: string` - - `"completed"` + The text to type. - - `"incomplete"` + - `type: "type"` - - `type: "shell_call"` + Specifies the event type. For a type action, this property is always set to `type`. - The type of the item. Always `shell_call`. + - `"type"` - - `"shell_call"` + - `Wait object { type }` - - `agent: optional object { agent_name }` + A wait action. - The agent that produced this item. + - `type: "wait"` - - `agent_name: string` + Specifies the event type. For a wait action, this property is always set to `wait`. - The canonical name of the agent that produced this item. + - `"wait"` - - `caller: optional object { type } or object { caller_id, type }` + - `actions: optional BetaComputerActionList` - The execution context that produced this tool call. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `Direct object { type }` + - `Click object { button, type, x, 2 more }` - - `type: "direct"` + A click action. - - `"direct"` + - `DoubleClick object { keys, type, x, y }` - - `Program object { caller_id, type }` + A double click action. - - `caller_id: string` + - `Drag object { path, type, keys }` - The call ID of the program item that produced this tool call. + A drag action. - - `type: "program"` + - `Keypress object { keys, type }` - - `"program"` + A collection of keypresses the model would like to perform. - - `created_by: optional string` + - `Move object { type, x, y, keys }` - The ID of the entity that created this tool call. + A mouse move action. - - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` + - `Screenshot object { type }` - The output of a shell tool call that was emitted. + A screenshot action. - - `id: string` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - The unique ID of the shell call output. Populated when this item is returned via API. + A scroll action. - - `call_id: string` + - `Type object { text, type }` - The unique ID of the shell tool call generated by the model. + An action to type in text. - - `max_output_length: number` + - `Wait object { type }` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + A wait action. - - `output: array of object { outcome, stderr, stdout, created_by }` + - `agent: optional object { agent_name }` - An array of shell call output contents + The agent that produced this item. - - `outcome: object { type } or object { exit_code, type }` + - `agent_name: string` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + The canonical name of the agent that produced this item. - - `Timeout object { type }` + - `ComputerCallOutput object { call_id, output, type, 4 more }` - Indicates that the shell call exceeded its configured time limit. + The output of a computer tool call. - - `type: "timeout"` + - `call_id: string` - The outcome type. Always `timeout`. + The ID of the computer tool call that produced the output. - - `"timeout"` + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `Exit object { exit_code, type }` + A computer screenshot image used with the computer use tool. - Indicates that the shell commands finished and returned an exit code. + - `type: "computer_screenshot"` - - `exit_code: number` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - Exit code from the shell process. + - `"computer_screenshot"` - - `type: "exit"` + - `file_id: optional string` - The outcome type. Always `exit`. + The identifier of an uploaded file that contains the screenshot. - - `"exit"` + - `image_url: optional string` - - `stderr: string` + The URL of the screenshot image. - The standard error output that was captured. + - `type: "computer_call_output"` - - `stdout: string` + The type of the computer tool call output. Always `computer_call_output`. - The standard output that was captured. + - `"computer_call_output"` - - `created_by: optional string` + - `id: optional string` - The identifier of the actor that created the item. + The ID of the computer tool call output. - - `status: "in_progress" or "completed" or "incomplete"` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + 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. - - `"incomplete"` + - `code: optional string` - - `type: "shell_call_output"` + The type of the pending safety check. - The type of the shell call output. Always `shell_call_output`. + - `message: optional string` - - `"shell_call_output"` + Details about the pending safety check. - `agent: optional object { agent_name }` @@ -190873,109 +191603,111 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. - - - `Direct object { type }` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `type: "direct"` + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - `"direct"` + - `"in_progress"` - - `Program object { caller_id, type }` + - `"completed"` - - `caller_id: string` + - `"incomplete"` - The call ID of the program item that produced this tool call. + - `WebSearchCall object { id, action, status, 2 more }` - - `type: "program"` + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `"program"` + - `id: string` - - `created_by: optional string` + The unique ID of the web search tool call. - The identifier of the actor that created the item. + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `ApplyPatchCall object { id, call_id, operation, 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). - A tool call that applies file diffs by creating, deleting, or updating files. + - `Search object { type, queries, query, sources }` - - `id: string` + Action type "search" - Performs a web search query. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `type: "search"` - - `call_id: string` + The action type. - The unique ID of the apply patch tool call generated by the model. + - `"search"` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `queries: optional array of string` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + The search queries. - - `CreateFile object { diff, path, type }` + - `query: optional string` - Instruction describing how to create a file via the apply_patch tool. + The search query. - - `diff: string` + - `sources: optional array of object { type, url }` - Diff to apply. + The sources used in the search. - - `path: string` + - `type: "url"` - Path of the file to create. + The type of source. Always `url`. - - `type: "create_file"` + - `"url"` - Create a new file with the provided diff. + - `url: string` - - `"create_file"` + The URL of the source. - - `DeleteFile object { path, type }` + - `OpenPage object { type, url }` - Instruction describing how to delete a file via the apply_patch tool. + Action type "open_page" - Opens a specific URL from search results. - - `path: string` + - `type: "open_page"` - Path of the file to delete. + The action type. - - `type: "delete_file"` + - `"open_page"` - Delete the specified file. + - `url: optional string` - - `"delete_file"` + The URL opened by the model. - - `UpdateFile object { diff, path, type }` + - `FindInPage object { pattern, type, url }` - Instruction describing how to update a file via the apply_patch tool. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `diff: string` + - `pattern: string` - Diff to apply. + The pattern or text to search for within the page. - - `path: string` + - `type: "find_in_page"` - Path of the file to update. + The action type. - - `type: "update_file"` + - `"find_in_page"` - Update an existing file with the provided diff. + - `url: string` - - `"update_file"` + The URL of the page searched for the pattern. - - `status: "in_progress" or "completed"` + - `status: "in_progress" or "searching" or "completed" or "failed"` - The status of the apply patch tool call. One of `in_progress` or `completed`. + 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`. + + - `"web_search_call"` - `agent: optional object { agent_name }` @@ -190985,55 +191717,32 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `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, 5 more }` + - `FunctionCall object { arguments, call_id, name, 6 more }` - The output emitted by an apply patch tool call. + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `id: string` + - `arguments: string` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + A JSON string of the arguments to pass to the function. - `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. - - `status: "completed" or "failed"` + - `name: string` - The status of the apply patch tool call output. One of `completed` or `failed`. + The name of the function to run. - - `"completed"` + - `type: "function_call"` - - `"failed"` + The type of the function tool call. Always `function_call`. - - `type: "apply_patch_call_output"` + - `"function_call"` - The type of the item. Always `apply_patch_call_output`. + - `id: optional string` - - `"apply_patch_call_output"` + The unique ID of the function tool call. - `agent: optional object { agent_name }` @@ -191063,180 +191772,160 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"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, 7 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` + - `namespace: optional string` - The name of the tool that was run. + The namespace of the function to run. - - `server_label: string` + - `status: optional "in_progress" or "completed" or "incomplete"` - The label of the MCP server running the tool. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `type: "mcp_call"` + - `"in_progress"` - The type of the item. Always `mcp_call`. + - `"completed"` - - `"mcp_call"` + - `"incomplete"` - - `agent: optional object { agent_name }` + - `FunctionCallOutput object { call_id, output, type, 4 more }` - The agent that produced this item. + The output of a function tool call. - - `agent_name: string` + - `call_id: string` - The canonical name of the agent that produced this item. + The unique ID of the function tool call generated by the model. - - `approval_request_id: optional string` + - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - 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. + Text, image, or file output of the function tool call. - - `error: optional string` + - `string` - The error from the tool call, if any. + A JSON string of the output of the function tool call. - - `output: optional string` + - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - The output from the tool call. + An array of content outputs (text, image, file) for the function tool call. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + A text input to the model. - - `"in_progress"` + - `text: string` - - `"completed"` + The text input to the model. - - `"incomplete"` + - `type: "input_text"` - - `"calling"` + The type of the input item. Always `input_text`. - - `"failed"` + - `"input_text"` - - `McpListTools object { id, server_label, tools, 3 more }` + - `prompt_cache_breakpoint: optional object { mode }` - A list of tools available on an MCP server. + 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. - - `id: string` + - `mode: "explicit"` - The unique ID of the list. + The breakpoint mode. Always `explicit`. - - `server_label: string` + - `"explicit"` - The label of the MCP server. + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - - `tools: array of object { input_schema, name, annotations, description }` + An image input to the model. Learn about [image inputs](/docs/guides/vision) - The tools available on the server. + - `type: "input_image"` - - `input_schema: unknown` + The type of the input item. Always `input_image`. - The JSON schema describing the tool's input. + - `"input_image"` - - `name: string` + - `detail: optional "low" or "high" or "auto" or "original"` - The name of the tool. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `annotations: optional unknown` + - `"low"` - Additional annotations about the tool. + - `"high"` - - `description: optional string` + - `"auto"` - The description of the tool. + - `"original"` - - `type: "mcp_list_tools"` + - `file_id: optional string` - The type of the item. Always `mcp_list_tools`. + The ID of the file to be sent to the model. - - `"mcp_list_tools"` + - `image_url: optional string` - - `agent: optional object { agent_name }` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - The agent that produced this item. + - `prompt_cache_breakpoint: optional object { mode }` - - `agent_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 canonical name of the agent that produced this item. + - `mode: "explicit"` - - `error: optional string` + The breakpoint mode. Always `explicit`. - Error message if the server could not list tools. + - `"explicit"` - - `McpApprovalRequest object { id, arguments, name, 3 more }` + - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` - A request for human approval of a tool invocation. + A file input to the model. - - `id: string` + - `type: "input_file"` - The unique ID of the approval request. + The type of the input item. Always `input_file`. - - `arguments: string` + - `"input_file"` - A JSON string of arguments for the tool. + - `detail: optional "auto" or "low" or "high"` - - `name: string` + 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 name of the tool to run. + - `"auto"` - - `server_label: string` + - `"low"` - The label of the MCP server making the request. + - `"high"` - - `type: "mcp_approval_request"` + - `file_data: optional string` - The type of the item. Always `mcp_approval_request`. + The base64-encoded data of the file to be sent to the model. - - `"mcp_approval_request"` + - `file_id: optional string` - - `agent: optional object { agent_name }` + The ID of the file to be sent to the model. - The agent that produced this item. + - `file_url: optional string` - - `agent_name: string` + The URL of the file to be sent to the model. - The canonical name of the agent that produced this item. + - `filename: optional string` - - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` + The name of the file to be sent to the model. - A response to an MCP approval request. + - `prompt_cache_breakpoint: optional object { mode }` - - `id: 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 approval response + - `mode: "explicit"` - - `approval_request_id: string` + The breakpoint mode. Always `explicit`. - The ID of the approval request being answered. + - `"explicit"` - - `approve: boolean` + - `type: "function_call_output"` - Whether the request was approved. + The type of the function tool call output. Always `function_call_output`. - - `type: "mcp_approval_response"` + - `"function_call_output"` - The type of the item. Always `mcp_approval_response`. + - `id: optional string` - - `"mcp_approval_response"` + The unique ID of the function tool call output. Populated when this item is returned via API. - `agent: optional object { agent_name }` @@ -191246,354 +191935,321 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `reason: optional string` + - `caller: optional object { type } or object { caller_id, type }` - Optional reason for the decision. + The execution context that produced this tool call. - - `CustomToolCall object { call_id, input, name, 5 more }` + - `Direct object { type }` - A call to a custom tool created by the model. + - `type: "direct"` - - `call_id: string` + The caller type. Always `direct`. - An identifier used to map this custom tool call to a tool call output. + - `"direct"` - - `input: string` + - `Program object { caller_id, type }` - The input for the custom tool call generated by the model. + - `caller_id: string` - - `name: string` + The call ID of the program item that produced this tool call. - The name of the custom tool being called. + - `type: "program"` - - `type: "custom_tool_call"` + The caller type. Always `program`. - The type of the custom tool call. Always `custom_tool_call`. + - `"program"` - - `"custom_tool_call"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `id: optional 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 custom tool call in the OpenAI platform. + - `"in_progress"` - - `agent: optional object { agent_name }` + - `"completed"` - The agent that produced this item. + - `"incomplete"` - - `agent_name: string` + - `AgentMessage object { author, content, recipient, 3 more }` - The canonical name of the agent that produced this item. + A message routed between agents. - - `caller: optional object { type } or object { caller_id, type }` + - `author: string` - The execution context that produced this tool call. + The sending agent identity. - - `Direct object { type }` + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - - `type: "direct"` + Plaintext, image, or encrypted content sent between agents. - - `"direct"` + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - - `Program object { caller_id, type }` + A text input to the model. - - `caller_id: string` + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - The call ID of the program item that produced this tool call. + An image input to the model. Learn about [image inputs](/docs/guides/vision) - - `type: "program"` + - `EncryptedContent object { encrypted_content, type }` - - `"program"` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `namespace: optional string` + - `encrypted_content: string` - The namespace of the custom tool being called. + Opaque encrypted content. - - `CustomToolCallOutput object { id, call_id, output, 5 more }` + - `type: "encrypted_content"` - - `id: string` + The type of the input item. Always `encrypted_content`. - The unique ID of the custom tool call output item. + - `"encrypted_content"` - - `call_id: string` + - `recipient: string` - The call ID, used to map this custom tool call output to a custom tool call. + The destination agent identity. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `type: "agent_message"` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + The item type. Always `agent_message`. - - `StringOutput = string` + - `"agent_message"` - A string of the output of the custom tool call. + - `id: optional string` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The unique ID of this agent message item. - Text, image, or file output of the custom tool call. + - `agent: optional object { agent_name }` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + The agent that produced this item. - A text input to the model. + - `agent_name: string` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + The canonical name of the agent that produced this item. - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `MultiAgentCall object { action, arguments, call_id, 3 more }` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - A file input to the model. + The multi-agent action that was executed. - - `status: "in_progress" or "completed" or "incomplete"` + - `"spawn_agent"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"interrupt_agent"` - - `"in_progress"` + - `"list_agents"` - - `"completed"` + - `"send_message"` - - `"incomplete"` + - `"followup_task"` - - `type: "custom_tool_call_output"` + - `"wait_agent"` - The type of the custom tool call output. Always `custom_tool_call_output`. + - `arguments: string` - - `"custom_tool_call_output"` + The action arguments as a JSON string. - - `agent: optional object { agent_name }` + - `call_id: string` - The agent that produced this item. + The unique ID linking this call to its output. - - `agent_name: string` + - `type: "multi_agent_call"` - The canonical name of the agent that produced this item. + The item type. Always `multi_agent_call`. - - `caller: optional object { type } or object { caller_id, type }` + - `"multi_agent_call"` - The execution context that produced this tool call. + - `id: optional string` - - `Direct object { type }` + The unique ID of this multi-agent call. - - `type: "direct"` + - `agent: optional object { agent_name }` - The caller type. Always `direct`. + The agent that produced this item. - - `"direct"` + - `agent_name: string` - - `Program object { caller_id, type }` + The canonical name of the agent that produced this item. - - `caller_id: string` + - `MultiAgentCallOutput object { action, call_id, output, 3 more }` - The call ID of the program item that produced this tool call. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `type: "program"` + The multi-agent action that produced this result. - The caller type. Always `program`. + - `"spawn_agent"` - - `"program"` + - `"interrupt_agent"` - - `created_by: optional string` + - `"list_agents"` - The identifier of the actor that created the item. + - `"send_message"` - - `parallel_tool_calls: boolean` + - `"followup_task"` - Whether to allow the model to run tool calls in parallel. + - `"wait_agent"` - - `temperature: number` + - `call_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 multi-agent call. - - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + - `output: array of object { text, type, annotations }` - 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. + Text output returned by the multi-agent action. - - `BetaToolChoiceOptions = "none" or "auto" or "required"` + - `text: string` - Controls which (if any) tool is called by the model. + The text content. - `none` means the model will not call any tool and instead generates a message. + - `type: "output_text"` - `auto` means the model can pick between generating a message or calling one or - more tools. + The content type. Always `output_text`. - `required` means the model must call one or more tools. + - `"output_text"` - - `"none"` + - `annotations: optional 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 }` - - `"auto"` + Citations associated with the text content. - - `"required"` + - `FileCitation object { file_id, filename, index, type }` - - `BetaToolChoiceAllowed object { mode, tools, type }` + - `file_id: string` - Constrains the tools available to the model to a pre-defined set. + The ID of the file. - - `mode: "auto" or "required"` + - `filename: string` - Constrains the tools available to the model to a pre-defined set. + The filename of the file cited. - `auto` allows the model to pick from among the allowed tools and generate a - message. + - `index: number` - `required` requires the model to call one or more of the allowed tools. + The index of the file in the list of files. - - `"auto"` + - `type: "file_citation"` - - `"required"` + The citation type. Always `file_citation`. - - `tools: array of map[unknown]` + - `"file_citation"` - A list of tool definitions that the model should be allowed to call. + - `URLCitation object { end_index, start_index, title, 2 more }` - For the Responses API, the list of tool definitions might look like: + - `end_index: number` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + The index of the last character of the citation in the message. - - `type: "allowed_tools"` + - `start_index: number` - Allowed tool configuration type. Always `allowed_tools`. + The index of the first character of the citation in the message. - - `"allowed_tools"` + - `title: string` - - `BetaToolChoiceTypes object { type }` + The title of the cited resource. - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](/docs/guides/tools). + - `type: "url_citation"` - - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + The citation type. Always `url_citation`. - The type of hosted tool the model should to use. Learn more about - [built-in tools](/docs/guides/tools). + - `"url_citation"` - Allowed values are: + - `url: string` - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + The URL of the cited resource. - - `"file_search"` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - - `"web_search_preview"` + - `container_id: string` - - `"computer"` + The ID of the container. - - `"computer_use_preview"` + - `end_index: number` - - `"computer_use"` + The index of the last character of the citation in the message. - - `"web_search_preview_2025_03_11"` + - `file_id: string` - - `"image_generation"` + The ID of the container file. - - `"code_interpreter"` + - `filename: string` - - `BetaToolChoiceFunction object { name, type }` + The filename of the container file cited. - Use this option to force the model to call a specific function. + - `start_index: number` - - `name: string` + The index of the first character of the citation in the message. - The name of the function to call. + - `type: "container_file_citation"` - - `type: "function"` + The citation type. Always `container_file_citation`. - For function calling, the type is always `function`. + - `"container_file_citation"` - - `"function"` + - `type: "multi_agent_call_output"` - - `BetaToolChoiceMcp object { server_label, type, name }` + The item type. Always `multi_agent_call_output`. - Use this option to force the model to call a specific tool on a remote MCP server. + - `"multi_agent_call_output"` - - `server_label: string` + - `id: optional string` - The label of the MCP server to use. + The unique ID of this multi-agent call output. - - `type: "mcp"` + - `agent: optional object { agent_name }` - For MCP tools, the type is always `mcp`. + The agent that produced this item. - - `"mcp"` + - `agent_name: string` - - `name: optional string` + The canonical name of the agent that produced this item. - The name of the tool to call on the server. + - `ToolSearchCall object { arguments, type, id, 4 more }` - - `BetaToolChoiceCustom object { name, type }` + - `arguments: unknown` - Use this option to force the model to call a specific custom tool. + The arguments supplied to the tool search call. - - `name: string` + - `type: "tool_search_call"` - The name of the custom tool to call. + The item type. Always `tool_search_call`. - - `type: "custom"` + - `"tool_search_call"` - For custom tool calling, the type is always `custom`. + - `id: optional string` - - `"custom"` + The unique ID of this tool search call. - - `BetaSpecificProgrammaticToolCallingParam object { type }` + - `agent: optional object { agent_name }` - - `type: "programmatic_tool_calling"` + The agent that produced this item. - The tool to call. Always `programmatic_tool_calling`. + - `agent_name: string` - - `"programmatic_tool_calling"` + The canonical name of the agent that produced this item. - - `BetaToolChoiceApplyPatch object { type }` + - `call_id: optional string` - Forces the model to call the apply_patch tool when executing a tool call. + The unique ID of the tool search call generated by the model. - - `type: "apply_patch"` + - `execution: optional "server" or "client"` - The tool to call. Always `apply_patch`. + Whether tool search was executed by the server or by the client. - - `"apply_patch"` + - `"server"` - - `BetaToolChoiceShell object { type }` + - `"client"` - Forces the model to call the shell tool when a tool call is required. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `type: "shell"` + The status of the tool search call. - The tool to call. Always `shell`. + - `"in_progress"` - - `"shell"` + - `"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"` - 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. + - `ToolSearchOutput object { tools, type, id, 4 more }` - We support the following categories of tools: + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - - **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. + The loaded tool definitions returned by the tool search output. - `Function object { name, parameters, strict, 5 more }` @@ -192114,8 +192770,40 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `BetaContainerNetworkPolicyDisabled object { type }` + - `type: "disabled"` + + Disable outbound network access. Always `disabled`. + + - `"disabled"` + - `BetaContainerNetworkPolicyAllowlist 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 BetaContainerNetworkPolicyDomainSecret` + + 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`. @@ -192296,10 +192984,128 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `BetaContainerAuto 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 BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `BetaContainerNetworkPolicyDisabled object { type }` + + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + + - `skills: optional array of BetaSkillReference or BetaInlineSkill` + + An optional list of skills referenced by id or inline data. + + - `BetaSkillReference 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. + + - `BetaInlineSkill object { description, name, source, type }` + + - `description: string` + + The description of the skill. + + - `name: string` + + The name of the skill. + + - `source: BetaInlineSkillSource` + + 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"` + - `BetaLocalEnvironment object { type, skills }` + - `type: "local"` + + Use a local computer environment. + + - `"local"` + + - `skills: optional array of BetaLocalSkill` + + 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. + - `BetaContainerReference 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) @@ -192584,279 +193390,343 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"programmatic"` - - `top_p: number` + - `type: "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. + The item type. Always `tool_search_output`. - We generally recommend altering this or `temperature` but not both. + - `"tool_search_output"` - - `background: optional boolean` + - `id: optional string` - Whether to run the model response in the background. - [Learn more](/docs/guides/background). + The unique ID of this tool search output. - - `completed_at: optional number` + - `agent: optional object { agent_name }` - Unix timestamp (in seconds) of when this Response was completed. - Only present when the status is `completed`. + The agent that produced this item. - - `conversation: optional object { id }` + - `agent_name: string` - The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. + The canonical name of the agent that produced this item. - - `id: string` + - `call_id: optional string` - The unique ID of the conversation that this response was associated with. + The unique ID of the tool search call generated by the model. - - `max_output_tokens: optional number` + - `execution: optional "server" or "client"` - 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). + Whether tool search was executed by the server or by the client. - - `max_tool_calls: optional number` + - `"server"` - 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. + - `"client"` - - `moderation: optional object { input, output }` + - `status: optional "in_progress" or "completed" or "incomplete"` - Moderation results for the response input and output, if moderated completions were requested. + The status of the tool search output. - - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + - `"in_progress"` - Moderation for the response input. + - `"completed"` - - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + - `"incomplete"` - A moderation result produced for the response input or output. + - `AdditionalTools object { role, tools, type, 2 more }` - - `categories: map[boolean]` + - `role: "developer"` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + The role that provided the additional tools. Only `developer` is supported. - - `category_applied_input_types: map[array of "text" or "image"]` + - `"developer"` - Which modalities of input are reflected by the score for each category. + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - - `"text"` + A list of additional tools made available at this item. - - `"image"` + - `Function object { name, parameters, strict, 5 more }` - - `category_scores: map[number]` + 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). - A dictionary of moderation categories to scores. + - `name: string` - - `flagged: boolean` + The name of the function to call. - A boolean indicating whether the content was flagged by any category. + - `parameters: map[unknown]` - - `model: string` + A JSON schema object describing the parameters of the function. - The moderation model that produced this result. + - `strict: boolean` - - `type: "moderation_result"` + Whether strict parameter validation is enforced for this function tool. - The object type, which was always `moderation_result` for successful moderation results. + - `type: "function"` - - `"moderation_result"` + The type of the function tool. Always `function`. - - `Error object { code, message, type }` + - `"function"` - An error produced while attempting moderation for the response input or output. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `code: string` + The tool invocation context(s). - The error code. + - `"direct"` - - `message: string` + - `"programmatic"` - The error message. + - `defer_loading: optional boolean` - - `type: "error"` + Whether this function is deferred and loaded via tool search. - The object type, which was always `error` for moderation failures. + - `description: optional string` - - `"error"` + A description of the function. Used by the model to determine whether or not to call the function. - - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` + - `output_schema: optional map[unknown]` - Moderation for the response output. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - A moderation result produced for the response input or output. + 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). - - `categories: map[boolean]` + - `type: "file_search"` - A dictionary of moderation categories to booleans, True if the input is flagged under this category. + The type of the file search tool. Always `file_search`. - - `category_applied_input_types: map[array of "text" or "image"]` + - `"file_search"` - Which modalities of input are reflected by the score for each category. + - `vector_store_ids: array of string` - - `"text"` + The IDs of the vector stores to search. - - `"image"` + - `filters: optional object { key, type, value } or object { filters, type }` - - `category_scores: map[number]` + A filter to apply. - A dictionary of moderation categories to scores. + - `ComparisonFilter object { key, type, value }` - - `flagged: boolean` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - A boolean indicating whether the content was flagged by any category. + - `key: string` - - `model: string` + The key to compare against the value. - The moderation model that produced this result. + - `type: "eq" or "ne" or "gt" or 5 more` - - `type: "moderation_result"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The object type, which was always `moderation_result` for successful moderation results. + - `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 - - `"moderation_result"` + - `"eq"` - - `Error object { code, message, type }` + - `"ne"` - An error produced while attempting moderation for the response input or output. + - `"gt"` - - `code: string` + - `"gte"` - The error code. + - `"lt"` - - `message: string` + - `"lte"` - The error message. + - `"in"` - - `type: "error"` + - `"nin"` - The object type, which was always `error` for moderation failures. + - `value: string or number or boolean or array of string or number` - - `"error"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `output_text: optional string` + - `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. + - `number` - - `previous_response_id: optional string` + - `boolean` - 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`. + - `array of string or number` - - `prompt: optional BetaResponsePrompt` + - `string` - Reference to a prompt template and its variables. - [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). + - `number` - - `id: string` + - `CompoundFilter object { filters, type }` - The unique identifier of the prompt template to use. + Combine multiple filters using `and` or `or`. - - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` + - `filters: array of object { key, type, value } or unknown` - 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. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `string` + - `ComparisonFilter object { key, type, value }` - - `BetaResponseInputText 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. + - `key: string` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + The key to compare against the value. - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `type: "eq" or "ne" or "gt" or 5 more` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - A file input to the model. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `version: optional string` + - `"eq"` - Optional version of the prompt template. + - `"ne"` - - `prompt_cache_key: optional string` + - `"gt"` - 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). + - `"gte"` - - `prompt_cache_options: optional object { mode, ttl }` + - `"lt"` - The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. + - `"lte"` - - `mode: "implicit" or "explicit"` + - `"in"` - Whether implicit prompt-cache breakpoints were enabled. + - `"nin"` - - `"implicit"` + - `value: string or number or boolean or array of string or number` - - `"explicit"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `ttl: "30m"` + - `string` - The minimum lifetime applied to each cache breakpoint. + - `number` - - `"30m"` + - `boolean` - - `prompt_cache_retention: optional "in_memory" or "24h"` + - `array of string or number` - Deprecated. Use `prompt_cache_options.ttl` instead. + - `string` - 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. + - `number` - For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: + - `unknown` - - Organizations without ZDR enabled default to `24h`. - - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. + - `type: "and" or "or"` - - `"in_memory"` + Type of operation: `and` or `or`. - - `"24h"` + - `"and"` - - `reasoning: optional object { context, effort, generate_summary, 2 more }` + - `"or"` - **gpt-5 and o-series models only** + - `max_num_results: optional number` - Configuration options for - [reasoning models](https://platform.openai.com/docs/guides/reasoning). + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `context: optional "auto" or "current_turn" or "all_turns"` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - 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`. + Ranking options for search. - When returned on a response, this is the effective reasoning context mode - used for the response. + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. - `"auto"` - - `"current_turn"` + - `"default-2024-11-15"` - - `"all_turns"` + - `score_threshold: optional number` - - `effort: optional "none" or "minimal" or "low" or 4 more` + The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. - 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. + - `Computer object { type }` - - `"none"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"minimal"` + - `type: "computer"` + + The type of the computer tool. Always `computer`. + + - `"computer"` + + - `ComputerUsePreview object { display_height, display_width, environment, type }` + + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + + - `display_height: number` + + The height of the computer display. + + - `display_width: number` + + The width of the computer display. + + - `environment: "windows" or "mac" or "linux" or 2 more` + + The type of computer environment to control. + + - `"windows"` + + - `"mac"` + + - `"linux"` + + - `"ubuntu"` + + - `"browser"` + + - `type: "computer_use_preview"` + + The type of the computer use tool. Always `computer_use_preview`. + + - `"computer_use_preview"` + + - `WebSearch object { type, filters, search_context_size, user_location }` + + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). + + - `type: "web_search" or "web_search_2025_08_26"` + + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + + - `"web_search"` + + - `"web_search_2025_08_26"` + + - `filters: optional object { allowed_domains }` + + Filters for the search. + + - `allowed_domains: optional array of string` + + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. + + Example: `["pubmed.ncbi.nlm.nih.gov"]` + + - `search_context_size: optional "low" or "medium" or "high"` + + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - `"low"` @@ -192864,2158 +193734,2465 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"high"` - - `"xhigh"` + - `user_location: optional object { city, country, region, 2 more }` - - `"max"` + The approximate location of the user. - - `generate_summary: optional "auto" or "concise" or "detailed"` + - `city: optional string` - **Deprecated:** use `summary` instead. + Free text input for the city of the user, e.g. `San Francisco`. - 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`. + - `country: optional string` + + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + + - `region: optional string` + + Free text input for the region of the user, e.g. `California`. + + - `timezone: optional string` + + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + + - `type: optional "approximate"` + + The type of location approximation. Always `approximate`. + + - `"approximate"` + + - `Mcp object { server_label, type, allowed_callers, 9 more }` + + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + + - `server_label: string` + + A label for this MCP server, used to identify it in tool calls. + + - `type: "mcp"` + + The type of the MCP tool. Always `mcp`. + + - `"mcp"` + + - `allowed_callers: optional array of "direct" or "programmatic"` + + The tool invocation context(s). + + - `"direct"` + + - `"programmatic"` + + - `allowed_tools: optional array of string or object { read_only, tool_names }` + + List of allowed tool names or a filter object. + + - `McpAllowedTools = array of string` + + A string array of allowed tool names + + - `McpToolFilter object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `authorization: optional string` + + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. + + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). + + Currently supported `connector_id` values are: + + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` + + - `"connector_dropbox"` + + - `"connector_gmail"` + + - `"connector_googlecalendar"` + + - `"connector_googledrive"` + + - `"connector_microsoftteams"` + + - `"connector_outlookcalendar"` + + - `"connector_outlookemail"` + + - `"connector_sharepoint"` + + - `defer_loading: optional boolean` + + Whether this MCP tool is deferred and discovered via tool search. + + - `headers: optional map[string]` + + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. + + - `require_approval: optional object { always, never } or "always" or "never"` + + Specify which of the MCP server's tools require approval. + + - `McpToolApprovalFilter object { always, never }` + + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. + + - `always: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `never: optional object { read_only, tool_names }` + + A filter object to specify which tools are allowed. + + - `read_only: optional boolean` + + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. + + - `tool_names: optional array of string` + + List of allowed tool names. + + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. + + - `"always"` + + - `"never"` + + - `server_description: optional string` + + Optional description of the MCP server, used to provide more context. + + - `server_url: optional string` + + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. + + - `tunnel_id: optional string` + + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. + + - `CodeInterpreter object { container, type, allowed_callers }` + + A tool that runs Python code to help generate a response to a prompt. + + - `container: string or object { type, file_ids, memory_limit, network_policy }` + + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. + + - `string` + + The container ID. + + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + + - `type: "auto"` + + Always `auto`. - `"auto"` - - `"concise"` + - `file_ids: optional array of string` - - `"detailed"` + An optional list of uploaded files to make available to your code. - - `mode: optional string or "standard" or "pro"` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - Controls the reasoning execution mode for the request. + The memory limit for the code interpreter container. - When returned on a response, this is the effective execution mode. + - `"1g"` + + - `"4g"` + + - `"16g"` + + - `"64g"` + + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + + Network access policy for the container. + + - `BetaContainerNetworkPolicyDisabled object { type }` + + - `BetaContainerNetworkPolicyAllowlist 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` - - `"standard" or "pro"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - Controls the reasoning execution mode for the request. + The image generation model to use. Default: `gpt-image-1`. - When returned on a response, this is the effective execution mode. + - `"gpt-image-1"` - - `"standard"` + - `"gpt-image-1-mini"` - - `"pro"` + - `"gpt-image-1.5"` - - `summary: optional "auto" or "concise" or "detailed"` + - `moderation: optional "auto" or "low"` - 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`. + Moderation level for the generated image. Default: `auto`. - `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. + - `"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"` - - `"concise"` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `"detailed"` + 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`. - - `safety_identifier: optional string` + - `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). + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `service_tier: optional "auto" or "default" or "flex" or 2 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`. - Specifies the processing type used for serving the request. + - `"1024x1024"` - - 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'. + - `"1024x1536"` - 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. + - `"1536x1024"` - `"auto"` - - `"default"` + - `LocalShell object { type }` - - `"flex"` + A tool that allows the model to execute shell commands in a local environment. - - `"scale"` + - `type: "local_shell"` - - `"priority"` + The type of the local shell tool. Always `local_shell`. - - `status: optional BetaResponseStatus` + - `"local_shell"` - The status of the response generation. One of `completed`, `failed`, - `in_progress`, `cancelled`, `queued`, or `incomplete`. + - `Shell object { type, allowed_callers, environment }` - - `"completed"` + A tool that allows the model to execute shell commands. - - `"failed"` + - `type: "shell"` - - `"in_progress"` + The type of the shell tool. Always `shell`. - - `"cancelled"` + - `"shell"` - - `"queued"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"incomplete"` + The tool invocation context(s). - - `text: optional BetaResponseTextConfig` + - `"direct"` - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `"programmatic"` - - [Text inputs and outputs](/docs/guides/text) - - [Structured Outputs](/docs/guides/structured-outputs) + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `format: optional BetaResponseFormatTextConfig` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - An object specifying the format that the model must output. + - `BetaLocalEnvironment object { type, skills }` - 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). + - `BetaContainerReference object { container_id, type }` - The default format is `{ "type": "text" }` with no additional options. + - `Custom object { name, type, allowed_callers, 3 more }` - **Not recommended for gpt-4o and newer models:** + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - 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. + - `name: string` - - `Text object { type }` + The name of the custom tool, used to identify it in tool calls. - Default response format. Used to generate text responses. + - `type: "custom"` - - `type: "text"` + The type of the custom tool. Always `custom`. - The type of response format being defined. Always `text`. + - `"custom"` - - `"text"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` + The tool invocation context(s). - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + - `"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 object { type } or object { definition, syntax, type }` + + The input format for the custom tool. Default is unconstrained text. + + - `Text object { type }` + + Unconstrained free-form text. + + - `type: "text"` - - `name: string` + Unconstrained text format. Always `text`. - 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. + - `"text"` - - `schema: map[unknown]` + - `Grammar object { definition, syntax, type }` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + A grammar defined by the user. - - `type: "json_schema"` + - `definition: string` - The type of response format being defined. Always `json_schema`. + The grammar definition. - - `"json_schema"` + - `syntax: "lark" or "regex"` - - `description: optional string` + The syntax of the grammar definition. One of `lark` or `regex`. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `"lark"` - - `strict: optional boolean` + - `"regex"` - 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: "grammar"` - - `JSONObject object { type }` + Grammar format. Always `grammar`. - 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. + - `"grammar"` - - `type: "json_object"` + - `Namespace object { description, name, tools, type }` - The type of response format being defined. Always `json_object`. + Groups function/custom tools under a shared namespace. - - `"json_object"` + - `description: string` - - `verbosity: optional "low" or "medium" or "high"` + A description of the namespace shown to the model. - 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`. + - `name: string` - - `"low"` + The namespace name used in tool calls (for example, `crm`). - - `"medium"` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `"high"` + The function/custom tools available inside this namespace. - - `top_logprobs: optional number` + - `Function object { name, type, allowed_callers, 5 more }` - 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. + - `name: string` - - `truncation: optional "auto" or "disabled"` + - `type: "function"` - The truncation strategy to use for the model response. + - `"function"` - - `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. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"auto"` + The tool invocation context(s). - - `"disabled"` + - `"direct"` - - `usage: optional BetaResponseUsage` + - `"programmatic"` - Represents token usage details including input tokens, output tokens, - a breakdown of output tokens, and the total tokens used. + - `defer_loading: optional boolean` - - `input_tokens: number` + Whether this function should be deferred and discovered via tool search. - The number of input tokens. + - `description: optional string` - - `input_tokens_details: object { cache_write_tokens, cached_tokens }` + - `output_schema: optional map[unknown]` - A detailed breakdown of the input tokens. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `cache_write_tokens: number` + - `parameters: optional unknown` - The number of input tokens that were written to the cache. + - `strict: optional boolean` - - `cached_tokens: number` + 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 number of tokens that were retrieved from the cache. - [More on prompt caching](/docs/guides/prompt-caching). + - `Custom object { name, type, allowed_callers, 3 more }` - - `output_tokens: number` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - The number of output tokens. + - `name: string` - - `output_tokens_details: object { reasoning_tokens }` + The name of the custom tool, used to identify it in tool calls. - A detailed breakdown of the output tokens. + - `type: "custom"` - - `reasoning_tokens: number` + The type of the custom tool. Always `custom`. - The number of reasoning tokens. + - `"custom"` - - `total_tokens: number` + - `allowed_callers: optional array of "direct" or "programmatic"` - The total number of tokens used. + The tool invocation context(s). - - `user: optional string` + - `"direct"` - 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). + - `"programmatic"` - - `sequence_number: number` + - `defer_loading: optional boolean` - The sequence number for this event. + Whether this tool should be deferred and discovered via tool search. - - `type: "response.completed"` + - `description: optional string` - The type of the event. Always `response.completed`. + Optional description of the custom tool, used to provide more context. - - `"response.completed"` + - `format: optional object { type } or object { definition, syntax, type }` - - `agent: optional object { agent_name }` + The input format for the custom tool. Default is unconstrained text. - The agent that owns this multi-agent streaming event. + - `Text object { type }` - - `agent_name: string` + Unconstrained free-form text. - The canonical name of the agent that produced this item. + - `type: "text"` - - `BetaResponseContentPartAddedEvent object { content_index, item_id, output_index, 4 more }` + Unconstrained text format. Always `text`. - Emitted when a new content part is added. + - `"text"` - - `content_index: number` + - `Grammar object { definition, syntax, type }` - The index of the content part that was added. + A grammar defined by the user. - - `item_id: string` + - `definition: string` - The ID of the output item that the content part was added to. + The grammar definition. - - `output_index: number` + - `syntax: "lark" or "regex"` - The index of the output item that the content part was added to. + The syntax of the grammar definition. One of `lark` or `regex`. - - `part: BetaResponseOutputText or BetaResponseOutputRefusal or object { text, type }` + - `"lark"` - The content part that was added. + - `"regex"` - - `BetaResponseOutputText object { annotations, logprobs, text, type }` + - `type: "grammar"` - A text output from the model. + Grammar format. Always `grammar`. - - `BetaResponseOutputRefusal object { refusal, type }` + - `"grammar"` - A refusal from the model. + - `type: "namespace"` - - `ReasoningText object { text, type }` + The type of the tool. Always `namespace`. - Reasoning text from the model. + - `"namespace"` - - `text: string` + - `ToolSearch object { type, description, execution, parameters }` - The reasoning text from the model. + Hosted or BYOT tool search configuration for deferred tools. - - `type: "reasoning_text"` + - `type: "tool_search"` - The type of the reasoning text. Always `reasoning_text`. + The type of the tool. Always `tool_search`. - - `"reasoning_text"` + - `"tool_search"` - - `sequence_number: number` + - `description: optional string` - The sequence number of this event. + Description shown to the model for a client-executed tool search tool. - - `type: "response.content_part.added"` + - `execution: optional "server" or "client"` - The type of the event. Always `response.content_part.added`. + Whether tool search is executed by the server or by the client. - - `"response.content_part.added"` + - `"server"` - - `agent: optional object { agent_name }` + - `"client"` - The agent that owns this multi-agent streaming event. + - `parameters: optional unknown` - - `agent_name: string` + Parameter schema for a client-executed tool search tool. - The canonical name of the agent that produced this item. + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `BetaResponseContentPartDoneEvent object { content_index, item_id, output_index, 4 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). - Emitted when a content part is done. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `content_index: number` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The index of the content part that is done. + - `"web_search_preview"` - - `item_id: string` + - `"web_search_preview_2025_03_11"` - The ID of the output item that the content part was added to. + - `search_content_types: optional array of "text" or "image"` - - `output_index: number` + - `"text"` - The index of the output item that the content part was added to. + - `"image"` - - `part: BetaResponseOutputText or BetaResponseOutputRefusal or object { text, type }` + - `search_context_size: optional "low" or "medium" or "high"` - The content part that is done. + 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. - - `BetaResponseOutputText object { annotations, logprobs, text, type }` + - `"low"` - A text output from the model. + - `"medium"` - - `BetaResponseOutputRefusal object { refusal, type }` + - `"high"` - A refusal from the model. + - `user_location: optional object { type, city, country, 2 more }` - - `ReasoningText object { text, type }` + The user's location. - Reasoning text from the model. + - `type: "approximate"` - - `text: string` + The type of location approximation. Always `approximate`. - The reasoning text from the model. + - `"approximate"` - - `type: "reasoning_text"` + - `city: optional string` - The type of the reasoning text. Always `reasoning_text`. + Free text input for the city of the user, e.g. `San Francisco`. - - `"reasoning_text"` + - `country: optional string` - - `sequence_number: number` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The sequence number of this event. + - `region: optional string` - - `type: "response.content_part.done"` + Free text input for the region of the user, e.g. `California`. - The type of the event. Always `response.content_part.done`. + - `timezone: optional string` - - `"response.content_part.done"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `agent: optional object { agent_name }` + - `ApplyPatch object { type, allowed_callers }` - The agent that owns this multi-agent streaming event. + Allows the assistant to create, delete, or update files using unified diffs. - - `agent_name: string` + - `type: "apply_patch"` - The canonical name of the agent that produced this item. + The type of the tool. Always `apply_patch`. - - `BetaResponseCreatedEvent object { response, sequence_number, type, agent }` + - `"apply_patch"` - An event that is emitted when a response is created. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `response: BetaResponse` + The tool invocation context(s). - The response that was created. + - `"direct"` - - `sequence_number: number` + - `"programmatic"` - The sequence number for this event. + - `type: "additional_tools"` - - `type: "response.created"` + The item type. Always `additional_tools`. - The type of the event. Always `response.created`. + - `"additional_tools"` - - `"response.created"` + - `id: optional string` + + The unique ID of this additional tools item. - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. - - `BetaResponseErrorEvent object { code, message, param, 3 more }` + - `Reasoning object { id, summary, type, 4 more }` - Emitted when an error occurs. + 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). - - `code: string` + - `id: string` - The error code. + The unique identifier of the reasoning content. - - `message: string` + - `summary: array of object { text, type }` - The error message. + Reasoning summary content. - - `param: string` + - `text: string` - The error parameter. + A summary of the reasoning output from the model so far. - - `sequence_number: number` + - `type: "summary_text"` - The sequence number of this event. + The type of the object. Always `summary_text`. - - `type: "error"` + - `"summary_text"` - The type of the event. Always `error`. + - `type: "reasoning"` - - `"error"` + The type of the object. Always `reasoning`. + + - `"reasoning"` - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. - - `BetaResponseFileSearchCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - - Emitted when a file search call is completed (results found). - - - `item_id: string` - - The ID of the output item that the file search call is initiated. + - `content: optional array of object { text, type }` - - `output_index: number` + Reasoning text content. - The index of the output item that the file search call is initiated. + - `text: string` - - `sequence_number: number` + The reasoning text from the model. - The sequence number of this event. + - `type: "reasoning_text"` - - `type: "response.file_search_call.completed"` + The type of the reasoning text. Always `reasoning_text`. - The type of the event. Always `response.file_search_call.completed`. + - `"reasoning_text"` - - `"response.file_search_call.completed"` + - `encrypted_content: optional string` - - `agent: optional object { agent_name }` + 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 agent that owns this multi-agent streaming event. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `agent_name: string` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The canonical name of the agent that produced this item. + - `"in_progress"` - - `BetaResponseFileSearchCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + - `"completed"` - Emitted when a file search call is initiated. + - `"incomplete"` - - `item_id: string` + - `Compaction object { encrypted_content, type, id, agent }` - The ID of the output item that the file search call is initiated. + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - - `output_index: number` + - `encrypted_content: string` - The index of the output item that the file search call is initiated. + The encrypted content of the compaction summary. - - `sequence_number: number` + - `type: "compaction"` - The sequence number of this event. + The type of the item. Always `compaction`. - - `type: "response.file_search_call.in_progress"` + - `"compaction"` - The type of the event. Always `response.file_search_call.in_progress`. + - `id: optional string` - - `"response.file_search_call.in_progress"` + The ID of the compaction item. - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. - - `BetaResponseFileSearchCallSearchingEvent object { item_id, output_index, sequence_number, 2 more }` + - `ImageGenerationCall object { id, result, status, 2 more }` - Emitted when a file search is currently searching. + An image generation request made by the model. - - `item_id: string` + - `id: string` - The ID of the output item that the file search call is initiated. + The unique ID of the image generation call. - - `output_index: number` + - `result: string` - The index of the output item that the file search call is searching. + The generated image encoded in base64. - - `sequence_number: number` + - `status: "in_progress" or "completed" or "generating" or "failed"` - The sequence number of this event. + The status of the image generation call. - - `type: "response.file_search_call.searching"` + - `"in_progress"` - The type of the event. Always `response.file_search_call.searching`. + - `"completed"` - - `"response.file_search_call.searching"` + - `"generating"` + + - `"failed"` + + - `type: "image_generation_call"` + + The type of the image generation call. Always `image_generation_call`. + + - `"image_generation_call"` - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. - - `BetaResponseFunctionCallArgumentsDeltaEvent object { delta, item_id, output_index, 3 more }` + - `CodeInterpreterCall object { id, code, container_id, 4 more }` - Emitted when there is a partial function-call arguments delta. + A tool call to run code. - - `delta: string` + - `id: string` - The function-call arguments delta that is added. + The unique ID of the code interpreter tool call. - - `item_id: string` + - `code: string` - The ID of the output item that the function-call arguments delta is added to. + The code to run, or null if not available. - - `output_index: number` + - `container_id: string` - The index of the output item that the function-call arguments delta is added to. + The ID of the container used to run the code. - - `sequence_number: number` + - `outputs: array of object { logs, type } or object { type, url }` - The sequence number of this event. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `type: "response.function_call_arguments.delta"` + - `Logs object { logs, type }` - The type of the event. Always `response.function_call_arguments.delta`. + The logs output from the code interpreter. - - `"response.function_call_arguments.delta"` + - `logs: string` - - `agent: optional object { agent_name }` + The logs output from the code interpreter. - The agent that owns this multi-agent streaming event. + - `type: "logs"` - - `agent_name: string` + The type of the output. Always `logs`. - The canonical name of the agent that produced this item. + - `"logs"` - - `BetaResponseFunctionCallArgumentsDoneEvent object { arguments, item_id, name, 4 more }` + - `Image object { type, url }` - Emitted when function-call arguments are finalized. + The image output from the code interpreter. - - `arguments: string` + - `type: "image"` - The function-call arguments. + The type of the output. Always `image`. - - `item_id: string` + - `"image"` - The ID of the item. + - `url: string` - - `name: string` + The URL of the image output from the code interpreter. - The name of the function that was called. + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - `output_index: number` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - The index of the output item. + - `"in_progress"` - - `sequence_number: number` + - `"completed"` - The sequence number of this event. + - `"incomplete"` - - `type: "response.function_call_arguments.done"` + - `"interpreting"` - - `"response.function_call_arguments.done"` + - `"failed"` + + - `type: "code_interpreter_call"` + + The type of the code interpreter tool call. Always `code_interpreter_call`. + + - `"code_interpreter_call"` - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. - - `BetaResponseInProgressEvent object { response, sequence_number, type, agent }` + - `LocalShellCall object { id, action, call_id, 3 more }` - Emitted when the response is in progress. + A tool call to run a command on the local shell. - - `response: BetaResponse` + - `id: string` - The response that is in progress. + The unique ID of the local shell call. - - `sequence_number: number` + - `action: object { command, env, type, 3 more }` - The sequence number of this event. + Execute a shell command on the server. - - `type: "response.in_progress"` + - `command: array of string` - The type of the event. Always `response.in_progress`. + The command to run. - - `"response.in_progress"` + - `env: map[string]` - - `agent: optional object { agent_name }` + Environment variables to set for the command. - The agent that owns this multi-agent streaming event. + - `type: "exec"` - - `agent_name: string` + The type of the local shell action. Always `exec`. - The canonical name of the agent that produced this item. + - `"exec"` - - `BetaResponseFailedEvent object { response, sequence_number, type, agent }` + - `timeout_ms: optional number` - An event that is emitted when a response fails. + Optional timeout in milliseconds for the command. - - `response: BetaResponse` + - `user: optional string` - The response that failed. + Optional user to run the command as. - - `sequence_number: number` + - `working_directory: optional string` - The sequence number of this event. + Optional working directory to run the command in. - - `type: "response.failed"` + - `call_id: string` - The type of the event. Always `response.failed`. + The unique ID of the local shell tool call generated by the model. - - `"response.failed"` + - `status: "in_progress" or "completed" or "incomplete"` + + The status of the local shell call. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `type: "local_shell_call"` + + The type of the local shell call. Always `local_shell_call`. + + - `"local_shell_call"` - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. - - `BetaResponseIncompleteEvent object { response, sequence_number, type, agent }` + - `LocalShellCallOutput object { id, output, type, 2 more }` - An event that is emitted when a response finishes as incomplete. + The output of a local shell tool call. - - `response: BetaResponse` + - `id: string` - The response that was incomplete. + The unique ID of the local shell tool call generated by the model. - - `sequence_number: number` + - `output: string` - The sequence number of this event. + A JSON string of the output of the local shell tool call. - - `type: "response.incomplete"` + - `type: "local_shell_call_output"` - The type of the event. Always `response.incomplete`. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `"response.incomplete"` + - `"local_shell_call_output"` - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. - - `BetaResponseOutputItemAddedEvent object { item, output_index, sequence_number, 2 more }` - - Emitted when a new output item is added. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `item: BetaResponseOutputItem` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - The output item that was added. + - `"in_progress"` - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + - `"completed"` - An output message from the model. + - `"incomplete"` - - `FileSearchCall object { id, queries, status, 3 more }` + - `ShellCall object { action, call_id, type, 5 more }` - The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + A tool representing a request to execute one or more shell commands. - - `FunctionCall object { arguments, call_id, name, 6 more }` + - `action: object { commands, max_output_length, timeout_ms }` - A tool call to run a function. See the - [function calling guide](/docs/guides/function-calling) for more information. + The shell commands and limits that describe how to run the tool call. - - `FunctionCallOutput object { id, call_id, output, 5 more }` + - `commands: array of string` - - `AgentMessage object { id, author, content, 3 more }` + Ordered shell commands for the execution environment to run. - - `MultiAgentCall object { id, action, arguments, 3 more }` + - `max_output_length: optional number` - - `MultiAgentCallOutput object { id, action, call_id, 3 more }` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `WebSearchCall object { id, action, status, 2 more }` + - `timeout_ms: optional number` - The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + - `call_id: string` - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + The unique ID of the shell tool call generated by the model. - - `ComputerCallOutput object { id, call_id, output, 5 more }` + - `type: "shell_call"` - - `Reasoning object { id, summary, type, 4 more }` + The type of the item. Always `shell_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). + - `"shell_call"` - - `Program object { id, call_id, code, 3 more }` + - `id: optional string` - - `ProgramOutput object { id, call_id, result, 3 more }` + The unique ID of the shell tool call. Populated when this item is returned via API. - - `ToolSearchCall object { id, arguments, call_id, 5 more }` + - `agent: optional object { agent_name }` - - `ToolSearchOutput object { id, call_id, execution, 5 more }` + The agent that produced this item. - - `AdditionalTools object { id, role, tools, 2 more }` + - `agent_name: string` - - `Compaction object { id, encrypted_content, type, 2 more }` + The canonical name of the agent that produced this item. - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + - `caller: optional object { type } or object { caller_id, type }` - - `ImageGenerationCall object { id, result, status, 2 more }` + The execution context that produced this tool call. - An image generation request made by the model. + - `Direct object { type }` - - `CodeInterpreterCall object { id, code, container_id, 4 more }` + - `type: "direct"` - A tool call to run code. + The caller type. Always `direct`. - - `LocalShellCall object { id, action, call_id, 3 more }` + - `"direct"` - A tool call to run a command on the local shell. + - `Program object { caller_id, type }` - - `LocalShellCallOutput object { id, output, type, 2 more }` + - `caller_id: string` - The output of a local shell tool call. + The call ID of the program item that produced this tool call. - - `ShellCall object { id, action, call_id, 6 more }` + - `type: "program"` - A tool call that executes one or more shell commands in a managed environment. + The caller type. Always `program`. - - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` + - `"program"` - The output of a shell tool call that was emitted. + - `environment: optional BetaLocalEnvironment or BetaContainerReference` - - `ApplyPatchCall object { id, call_id, operation, 5 more }` + The environment to execute the shell commands in. - A tool call that applies file diffs by creating, deleting, or updating files. + - `BetaLocalEnvironment object { type, skills }` - - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` + - `BetaContainerReference object { container_id, type }` - The output emitted by an apply patch tool call. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `McpCall object { id, arguments, name, 7 more }` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - An invocation of a tool on an MCP server. + - `"in_progress"` - - `McpListTools object { id, server_label, tools, 3 more }` + - `"completed"` - A list of tools available on an MCP server. + - `"incomplete"` - - `McpApprovalRequest object { id, arguments, name, 3 more }` + - `ShellCallOutput object { call_id, output, type, 5 more }` - A request for human approval of a tool invocation. + The streamed output items emitted by a shell tool call. - - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` + - `call_id: string` - A response to an MCP approval request. + The unique ID of the shell tool call generated by the model. - - `CustomToolCall object { call_id, input, name, 5 more }` + - `output: array of BetaResponseFunctionShellCallOutputContent` - A call to a custom tool created by the model. + Captured chunks of stdout and stderr output, along with their associated outcomes. - - `CustomToolCallOutput object { id, call_id, output, 5 more }` + - `outcome: object { type } or object { exit_code, type }` - - `output_index: number` + The exit or timeout outcome associated with this shell call. - The index of the output item that was added. + - `Timeout object { type }` - - `sequence_number: number` + Indicates that the shell call exceeded its configured time limit. - The sequence number of this event. + - `type: "timeout"` - - `type: "response.output_item.added"` + The outcome type. Always `timeout`. - The type of the event. Always `response.output_item.added`. + - `"timeout"` - - `"response.output_item.added"` + - `Exit object { exit_code, type }` - - `agent: optional object { agent_name }` + Indicates that the shell commands finished and returned an exit code. - The agent that owns this multi-agent streaming event. + - `exit_code: number` - - `agent_name: string` + The exit code returned by the shell process. - The canonical name of the agent that produced this item. + - `type: "exit"` - - `BetaResponseOutputItemDoneEvent object { item, output_index, sequence_number, 2 more }` + The outcome type. Always `exit`. - Emitted when an output item is marked done. + - `"exit"` - - `item: BetaResponseOutputItem` + - `stderr: string` - The output item that was marked done. + Captured stderr output for the shell call. - - `output_index: number` + - `stdout: string` - The index of the output item that was marked done. + Captured stdout output for the shell call. - - `sequence_number: number` + - `type: "shell_call_output"` - The sequence number of this event. + The type of the item. Always `shell_call_output`. - - `type: "response.output_item.done"` + - `"shell_call_output"` - The type of the event. Always `response.output_item.done`. + - `id: optional string` - - `"response.output_item.done"` + The unique ID of the shell tool call output. Populated when this item is returned via API. - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. - - `BetaResponseReasoningSummaryPartAddedEvent object { item_id, output_index, part, 4 more }` + - `caller: optional object { type } or object { caller_id, type }` - Emitted when a new reasoning summary part is added. + The execution context that produced this tool call. - - `item_id: string` + - `Direct object { type }` - The ID of the item this summary part is associated with. + - `type: "direct"` - - `output_index: number` + The caller type. Always `direct`. - The index of the output item this summary part is associated with. + - `"direct"` - - `part: object { text, type }` + - `Program object { caller_id, type }` - The summary part that was added. + - `caller_id: string` - - `text: string` + The call ID of the program item that produced this tool call. - The text of the summary part. + - `type: "program"` - - `type: "summary_text"` + The caller type. Always `program`. - The type of the summary part. Always `summary_text`. + - `"program"` - - `"summary_text"` + - `max_output_length: optional number` - - `sequence_number: number` + The maximum number of UTF-8 characters captured for this shell call's combined output. - The sequence number of this event. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `summary_index: number` + The status of the shell call output. - The index of the summary part within the reasoning summary. + - `"in_progress"` - - `type: "response.reasoning_summary_part.added"` + - `"completed"` - The type of the event. Always `response.reasoning_summary_part.added`. + - `"incomplete"` - - `"response.reasoning_summary_part.added"` + - `ApplyPatchCall object { call_id, operation, status, 4 more }` - - `agent: optional object { agent_name }` + A tool call representing a request to create, delete, or update files using diff patches. - The agent that owns this multi-agent streaming event. + - `call_id: string` - - `agent_name: string` + The unique ID of the apply patch tool call generated by the model. - The canonical name of the agent that produced this item. + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - - `BetaResponseReasoningSummaryPartDoneEvent object { item_id, output_index, part, 5 more }` + The specific create, delete, or update instruction for the apply_patch tool call. - Emitted when a reasoning summary part is completed. + - `CreateFile object { diff, path, type }` - - `item_id: string` + Instruction for creating a new file via the apply_patch tool. - The ID of the item this summary part is associated with. + - `diff: string` - - `output_index: number` + Unified diff content to apply when creating the file. - The index of the output item this summary part is associated with. + - `path: string` - - `part: object { text, type }` + Path of the file to create relative to the workspace root. - The completed summary part. + - `type: "create_file"` - - `text: string` + The operation type. Always `create_file`. - The text of the summary part. + - `"create_file"` - - `type: "summary_text"` + - `DeleteFile object { path, type }` - The type of the summary part. Always `summary_text`. + Instruction for deleting an existing file via the apply_patch tool. - - `"summary_text"` + - `path: string` - - `sequence_number: number` + Path of the file to delete relative to the workspace root. - The sequence number of this event. + - `type: "delete_file"` - - `summary_index: number` + The operation type. Always `delete_file`. - The index of the summary part within the reasoning summary. + - `"delete_file"` - - `type: "response.reasoning_summary_part.done"` + - `UpdateFile object { diff, path, type }` - The type of the event. Always `response.reasoning_summary_part.done`. + Instruction for updating an existing file via the apply_patch tool. - - `"response.reasoning_summary_part.done"` + - `diff: string` - - `agent: optional object { agent_name }` + Unified diff content to apply to the existing file. - The agent that owns this multi-agent streaming event. + - `path: string` - - `agent_name: string` + Path of the file to update relative to the workspace root. - The canonical name of the agent that produced this item. + - `type: "update_file"` - - `status: optional "incomplete"` + The operation type. Always `update_file`. - The completion status of the summary part. Omitted when the part completed - normally and set to `incomplete` when generation was interrupted. + - `"update_file"` - - `"incomplete"` + - `status: "in_progress" or "completed"` - - `BetaResponseReasoningSummaryTextDeltaEvent object { delta, item_id, output_index, 4 more }` + The status of the apply patch tool call. One of `in_progress` or `completed`. - Emitted when a delta is added to a reasoning summary text. + - `"in_progress"` - - `delta: string` + - `"completed"` - The text delta that was added to the summary. + - `type: "apply_patch_call"` - - `item_id: string` + The type of the item. Always `apply_patch_call`. - The ID of the item this summary text delta is associated with. + - `"apply_patch_call"` - - `output_index: number` + - `id: optional string` - The index of the output item this summary text delta is associated with. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `sequence_number: number` + - `agent: optional object { agent_name }` - The sequence number of this event. + The agent that produced this item. - - `summary_index: number` + - `agent_name: string` - The index of the summary part within the reasoning summary. + The canonical name of the agent that produced this item. - - `type: "response.reasoning_summary_text.delta"` + - `caller: optional object { type } or object { caller_id, type }` - The type of the event. Always `response.reasoning_summary_text.delta`. + The execution context that produced this tool call. - - `"response.reasoning_summary_text.delta"` + - `Direct object { type }` - - `agent: optional object { agent_name }` + - `type: "direct"` - The agent that owns this multi-agent streaming event. + The caller type. Always `direct`. - - `agent_name: string` + - `"direct"` - The canonical name of the agent that produced this item. + - `Program object { caller_id, type }` - - `BetaResponseReasoningSummaryTextDoneEvent object { item_id, output_index, sequence_number, 4 more }` + - `caller_id: string` - Emitted when a reasoning summary text is completed. + The call ID of the program item that produced this tool call. - - `item_id: string` + - `type: "program"` - The ID of the item this summary text is associated with. + The caller type. Always `program`. - - `output_index: number` + - `"program"` - The index of the output item this summary text is associated with. + - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` - - `sequence_number: number` + The streamed output emitted by an apply patch tool call. - The sequence number of this event. + - `call_id: string` - - `summary_index: number` + The unique ID of the apply patch tool call generated by the model. - The index of the summary part within the reasoning summary. + - `status: "completed" or "failed"` - - `text: string` + The status of the apply patch tool call output. One of `completed` or `failed`. - The full text of the completed reasoning summary. + - `"completed"` - - `type: "response.reasoning_summary_text.done"` + - `"failed"` - The type of the event. Always `response.reasoning_summary_text.done`. + - `type: "apply_patch_call_output"` - - `"response.reasoning_summary_text.done"` + The type of the item. Always `apply_patch_call_output`. + + - `"apply_patch_call_output"` + + - `id: optional string` + + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. - - `BetaResponseReasoningTextDeltaEvent object { content_index, delta, item_id, 4 more }` - - Emitted when a delta is added to a reasoning text. + - `caller: optional object { type } or object { caller_id, type }` - - `content_index: number` + The execution context that produced this tool call. - The index of the reasoning content part this delta is associated with. + - `Direct object { type }` - - `delta: string` + - `type: "direct"` - The text delta that was added to the reasoning content. + The caller type. Always `direct`. - - `item_id: string` + - `"direct"` - The ID of the item this reasoning text delta is associated with. + - `Program object { caller_id, type }` - - `output_index: number` + - `caller_id: string` - The index of the output item this reasoning text delta is associated with. + The call ID of the program item that produced this tool call. - - `sequence_number: number` + - `type: "program"` - The sequence number of this event. + The caller type. Always `program`. - - `type: "response.reasoning_text.delta"` + - `"program"` - The type of the event. Always `response.reasoning_text.delta`. + - `output: optional string` - - `"response.reasoning_text.delta"` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - `agent: optional object { agent_name }` + - `McpListTools object { id, server_label, tools, 3 more }` - The agent that owns this multi-agent streaming event. + A list of tools available on an MCP server. - - `agent_name: string` + - `id: string` - The canonical name of the agent that produced this item. + The unique ID of the list. - - `BetaResponseReasoningTextDoneEvent object { content_index, item_id, output_index, 4 more }` + - `server_label: string` - Emitted when a reasoning text is completed. + The label of the MCP server. - - `content_index: number` + - `tools: array of object { input_schema, name, annotations, description }` - The index of the reasoning content part. + The tools available on the server. - - `item_id: string` + - `input_schema: unknown` - The ID of the item this reasoning text is associated with. + The JSON schema describing the tool's input. - - `output_index: number` + - `name: string` - The index of the output item this reasoning text is associated with. + The name of the tool. - - `sequence_number: number` + - `annotations: optional unknown` - The sequence number of this event. + Additional annotations about the tool. - - `text: string` + - `description: optional string` - The full text of the completed reasoning content. + The description of the tool. - - `type: "response.reasoning_text.done"` + - `type: "mcp_list_tools"` - The type of the event. Always `response.reasoning_text.done`. + The type of the item. Always `mcp_list_tools`. - - `"response.reasoning_text.done"` + - `"mcp_list_tools"` - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. - - `BetaResponseRefusalDeltaEvent object { content_index, delta, item_id, 4 more }` + - `error: optional string` - Emitted when there is a partial refusal text. + Error message if the server could not list tools. - - `content_index: number` + - `McpApprovalRequest object { id, arguments, name, 3 more }` - The index of the content part that the refusal text is added to. + A request for human approval of a tool invocation. - - `delta: string` + - `id: string` - The refusal text that is added. + The unique ID of the approval request. - - `item_id: string` + - `arguments: string` - The ID of the output item that the refusal text is added to. + A JSON string of arguments for the tool. - - `output_index: number` + - `name: string` - The index of the output item that the refusal text is added to. + The name of the tool to run. - - `sequence_number: number` + - `server_label: string` - The sequence number of this event. + The label of the MCP server making the request. - - `type: "response.refusal.delta"` + - `type: "mcp_approval_request"` - The type of the event. Always `response.refusal.delta`. + The type of the item. Always `mcp_approval_request`. - - `"response.refusal.delta"` + - `"mcp_approval_request"` - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. - - `BetaResponseRefusalDoneEvent object { content_index, item_id, output_index, 4 more }` - - Emitted when refusal text is finalized. - - - `content_index: number` - - The index of the content part that the refusal text is finalized. - - - `item_id: string` + - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` - The ID of the output item that the refusal text is finalized. + A response to an MCP approval request. - - `output_index: number` + - `approval_request_id: string` - The index of the output item that the refusal text is finalized. + The ID of the approval request being answered. - - `refusal: string` + - `approve: boolean` - The refusal text that is finalized. + Whether the request was approved. - - `sequence_number: number` + - `type: "mcp_approval_response"` - The sequence number of this event. + The type of the item. Always `mcp_approval_response`. - - `type: "response.refusal.done"` + - `"mcp_approval_response"` - The type of the event. Always `response.refusal.done`. + - `id: optional string` - - `"response.refusal.done"` + The unique ID of the approval response - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. - - `BetaResponseTextDeltaEvent object { content_index, delta, item_id, 5 more }` - - Emitted when there is an additional text delta. - - - `content_index: number` - - The index of the content part that the text delta was added to. - - - `delta: string` - - The text delta that was added. + - `reason: optional string` - - `item_id: string` + Optional reason for the decision. - The ID of the output item that the text delta was added to. + - `McpCall object { id, arguments, name, 7 more }` - - `logprobs: array of object { token, logprob, top_logprobs }` + An invocation of a tool on an MCP server. - The log probabilities of the tokens in the delta. + - `id: string` - - `token: string` + The unique ID of the tool call. - A possible text token. + - `arguments: string` - - `logprob: number` + A JSON string of the arguments passed to the tool. - The log probability of this token. + - `name: string` - - `top_logprobs: optional array of object { token, logprob }` + The name of the tool that was run. - The log probabilities of up to 20 of the most likely tokens. + - `server_label: string` - - `token: optional string` + The label of the MCP server running the tool. - A possible text token. + - `type: "mcp_call"` - - `logprob: optional number` + The type of the item. Always `mcp_call`. - The log probability of this token. + - `"mcp_call"` - - `output_index: number` + - `agent: optional object { agent_name }` - The index of the output item that the text delta was added to. + The agent that produced this item. - - `sequence_number: number` + - `agent_name: string` - The sequence number for this event. + The canonical name of the agent that produced this item. - - `type: "response.output_text.delta"` + - `approval_request_id: optional string` - The type of the event. Always `response.output_text.delta`. + 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. - - `"response.output_text.delta"` + - `error: optional string` - - `agent: optional object { agent_name }` + The error from the tool call, if any. - The agent that owns this multi-agent streaming event. + - `output: optional string` - - `agent_name: string` + The output from the tool call. - The canonical name of the agent that produced this item. + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `BetaResponseTextDoneEvent object { content_index, item_id, logprobs, 5 more }` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - Emitted when text content is finalized. + - `"in_progress"` - - `content_index: number` + - `"completed"` - The index of the content part that the text content is finalized. + - `"incomplete"` - - `item_id: string` + - `"calling"` - The ID of the output item that the text content is finalized. + - `"failed"` - - `logprobs: array of object { token, logprob, top_logprobs }` + - `CustomToolCallOutput object { call_id, output, type, 3 more }` - The log probabilities of the tokens in the delta. + The output of a custom tool call from your code, being sent back to the model. - - `token: string` + - `call_id: string` - A possible text token. + The call ID, used to map this custom tool call output to a custom tool call. - - `logprob: number` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The log probability of this token. + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `top_logprobs: optional array of object { token, logprob }` + - `StringOutput = string` - The log probabilities of up to 20 of the most likely tokens. + A string of the output of the custom tool call. - - `token: optional string` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - A possible text token. + Text, image, or file output of the custom tool call. - - `logprob: optional number` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - The log probability of this token. + A text input to the model. - - `output_index: number` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - The index of the output item that the text content is finalized. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `sequence_number: number` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - The sequence number for this event. + A file input to the model. - - `text: string` + - `type: "custom_tool_call_output"` - The text content that is finalized. + The type of the custom tool call output. Always `custom_tool_call_output`. - - `type: "response.output_text.done"` + - `"custom_tool_call_output"` - The type of the event. Always `response.output_text.done`. + - `id: optional string` - - `"response.output_text.done"` + The unique ID of the custom tool call output in the OpenAI platform. - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. - - `BetaResponseWebSearchCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - - Emitted when a web search call is completed. + - `caller: optional object { type } or object { caller_id, type }` - - `item_id: string` + The execution context that produced this tool call. - Unique ID for the output item associated with the web search call. + - `Direct object { type }` - - `output_index: number` + - `type: "direct"` - The index of the output item that the web search call is associated with. + The caller type. Always `direct`. - - `sequence_number: number` + - `"direct"` - The sequence number of the web search call being processed. + - `Program object { caller_id, type }` - - `type: "response.web_search_call.completed"` + - `caller_id: string` - The type of the event. Always `response.web_search_call.completed`. + The call ID of the program item that produced this tool call. - - `"response.web_search_call.completed"` + - `type: "program"` - - `agent: optional object { agent_name }` + The caller type. Always `program`. - The agent that owns this multi-agent streaming event. + - `"program"` - - `agent_name: string` + - `CustomToolCall object { call_id, input, name, 5 more }` - The canonical name of the agent that produced this item. + A call to a custom tool created by the model. - - `BetaResponseWebSearchCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + - `call_id: string` - Emitted when a web search call is initiated. + An identifier used to map this custom tool call to a tool call output. - - `item_id: string` + - `input: string` - Unique ID for the output item associated with the web search call. + The input for the custom tool call generated by the model. - - `output_index: number` + - `name: string` - The index of the output item that the web search call is associated with. + The name of the custom tool being called. - - `sequence_number: number` + - `type: "custom_tool_call"` - The sequence number of the web search call being processed. + The type of the custom tool call. Always `custom_tool_call`. - - `type: "response.web_search_call.in_progress"` + - `"custom_tool_call"` - The type of the event. Always `response.web_search_call.in_progress`. + - `id: optional string` - - `"response.web_search_call.in_progress"` + The unique ID of the custom tool call in the OpenAI platform. - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. - - `BetaResponseWebSearchCallSearchingEvent object { item_id, output_index, sequence_number, 2 more }` - - Emitted when a web search call is executing. + - `caller: optional object { type } or object { caller_id, type }` - - `item_id: string` + The execution context that produced this tool call. - Unique ID for the output item associated with the web search call. + - `Direct object { type }` - - `output_index: number` + - `type: "direct"` - The index of the output item that the web search call is associated with. + - `"direct"` - - `sequence_number: number` + - `Program object { caller_id, type }` - The sequence number of the web search call being processed. + - `caller_id: string` - - `type: "response.web_search_call.searching"` + The call ID of the program item that produced this tool call. - The type of the event. Always `response.web_search_call.searching`. + - `type: "program"` - - `"response.web_search_call.searching"` + - `"program"` - - `agent: optional object { agent_name }` + - `namespace: optional string` - The agent that owns this multi-agent streaming event. + The namespace of the custom tool being called. - - `agent_name: string` + - `CompactionTrigger object { type, agent }` - The canonical name of the agent that produced this item. + Compacts the current context. Must be the final input item. - - `BetaResponseImageGenCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` + - `type: "compaction_trigger"` - Emitted when an image generation tool call has completed and the final image is available. + The type of the item. Always `compaction_trigger`. - - `item_id: string` + - `"compaction_trigger"` - The unique identifier of the image generation item being processed. + - `agent: optional object { agent_name }` - - `output_index: number` + The agent that produced this item. - The index of the output item in the response's output array. + - `agent_name: string` - - `sequence_number: number` + The canonical name of the agent that produced this item. - The sequence number of this event. + - `ItemReference object { id, agent, type }` - - `type: "response.image_generation_call.completed"` + An internal identifier for an item to reference. - The type of the event. Always 'response.image_generation_call.completed'. + - `id: string` - - `"response.image_generation_call.completed"` + The ID of the item to reference. - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. - - `BetaResponseImageGenCallGeneratingEvent object { item_id, output_index, sequence_number, 2 more }` + - `type: optional "item_reference"` - Emitted when an image generation tool call is actively generating an image (intermediate state). + The type of item to reference. Always `item_reference`. - - `item_id: string` + - `"item_reference"` - The unique identifier of the image generation item being processed. + - `Program object { id, call_id, code, 3 more }` - - `output_index: number` + - `id: string` - The index of the output item in the response's output array. + The unique ID of this program item. - - `sequence_number: number` + - `call_id: string` - The sequence number of the image generation item being processed. + The stable call ID of the program item. - - `type: "response.image_generation_call.generating"` + - `code: string` - The type of the event. Always 'response.image_generation_call.generating'. + The JavaScript source executed by programmatic tool calling. - - `"response.image_generation_call.generating"` + - `fingerprint: string` + + Opaque program replay fingerprint that must be round-tripped. + + - `type: "program"` + + The item type. Always `program`. + + - `"program"` - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. - - `BetaResponseImageGenCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + - `ProgramOutput object { id, call_id, result, 3 more }` - Emitted when an image generation tool call is in progress. + - `id: string` - - `item_id: string` + The unique ID of this program output item. - The unique identifier of the image generation item being processed. + - `call_id: string` - - `output_index: number` + The call ID of the program item. - The index of the output item in the response's output array. + - `result: string` - - `sequence_number: number` + The result produced by the program item. - The sequence number of the image generation item being processed. + - `status: "completed" or "incomplete"` - - `type: "response.image_generation_call.in_progress"` + The terminal status of the program output. - The type of the event. Always 'response.image_generation_call.in_progress'. + - `"completed"` - - `"response.image_generation_call.in_progress"` + - `"incomplete"` + + - `type: "program_output"` + + The item type. Always `program_output`. + + - `"program_output"` - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. - - `BetaResponseImageGenCallPartialImageEvent object { item_id, output_index, partial_image_b64, 4 more }` - - Emitted when a partial image is available during image generation streaming. + - `metadata: map[string]` - - `item_id: string` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - The unique identifier of the image generation item being processed. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `output_index: number` + - `model: "gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more or string` - The index of the output item in the response's output array. + 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. - - `partial_image_b64: string` + - `"gpt-5.6-sol" or "gpt-5.6-terra" or "gpt-5.6-luna" or 92 more` - Base64-encoded partial image data, suitable for rendering as an image. + 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. - - `partial_image_index: number` + - `"gpt-5.6-sol"` - 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). + - `"gpt-5.6-terra"` - - `sequence_number: number` + - `"gpt-5.6-luna"` - The sequence number of the image generation item being processed. + - `"gpt-5.4"` - - `type: "response.image_generation_call.partial_image"` + - `"gpt-5.4-mini"` - The type of the event. Always 'response.image_generation_call.partial_image'. + - `"gpt-5.4-nano"` - - `"response.image_generation_call.partial_image"` + - `"gpt-5.4-mini-2026-03-17"` - - `agent: optional object { agent_name }` + - `"gpt-5.4-nano-2026-03-17"` - The agent that owns this multi-agent streaming event. + - `"gpt-5.3-chat-latest"` - - `agent_name: string` + - `"gpt-5.2"` - The canonical name of the agent that produced this item. + - `"gpt-5.2-2025-12-11"` - - `BetaResponseMcpCallArgumentsDeltaEvent object { delta, item_id, output_index, 3 more }` + - `"gpt-5.2-chat-latest"` - Emitted when there is a delta (partial update) to the arguments of an MCP tool call. + - `"gpt-5.2-pro"` - - `delta: string` + - `"gpt-5.2-pro-2025-12-11"` - A JSON string containing the partial update to the arguments for the MCP tool call. + - `"gpt-5.1"` - - `item_id: string` + - `"gpt-5.1-2025-11-13"` - The unique identifier of the MCP tool call item being processed. + - `"gpt-5.1-codex"` - - `output_index: number` + - `"gpt-5.1-mini"` - The index of the output item in the response's output array. + - `"gpt-5.1-chat-latest"` - - `sequence_number: number` + - `"gpt-5"` - The sequence number of this event. + - `"gpt-5-mini"` - - `type: "response.mcp_call_arguments.delta"` + - `"gpt-5-nano"` - The type of the event. Always 'response.mcp_call_arguments.delta'. + - `"gpt-5-2025-08-07"` - - `"response.mcp_call_arguments.delta"` + - `"gpt-5-mini-2025-08-07"` - - `agent: optional object { agent_name }` + - `"gpt-5-nano-2025-08-07"` - The agent that owns this multi-agent streaming event. + - `"gpt-5-chat-latest"` - - `agent_name: string` + - `"gpt-4.1"` - The canonical name of the agent that produced this item. + - `"gpt-4.1-mini"` - - `BetaResponseMcpCallArgumentsDoneEvent object { arguments, item_id, output_index, 3 more }` + - `"gpt-4.1-nano"` - Emitted when the arguments for an MCP tool call are finalized. + - `"gpt-4.1-2025-04-14"` - - `arguments: string` + - `"gpt-4.1-mini-2025-04-14"` - A JSON string containing the finalized arguments for the MCP tool call. + - `"gpt-4.1-nano-2025-04-14"` - - `item_id: string` + - `"o4-mini"` - The unique identifier of the MCP tool call item being processed. + - `"o4-mini-2025-04-16"` - - `output_index: number` + - `"o3"` - The index of the output item in the response's output array. + - `"o3-2025-04-16"` - - `sequence_number: number` + - `"o3-mini"` - The sequence number of this event. + - `"o3-mini-2025-01-31"` - - `type: "response.mcp_call_arguments.done"` + - `"o1"` - The type of the event. Always 'response.mcp_call_arguments.done'. + - `"o1-2024-12-17"` - - `"response.mcp_call_arguments.done"` + - `"o1-preview"` - - `agent: optional object { agent_name }` + - `"o1-preview-2024-09-12"` - The agent that owns this multi-agent streaming event. + - `"o1-mini"` - - `agent_name: string` + - `"o1-mini-2024-09-12"` - The canonical name of the agent that produced this item. + - `"gpt-4o"` - - `BetaResponseMcpCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` + - `"gpt-4o-2024-11-20"` - Emitted when an MCP tool call has completed successfully. + - `"gpt-4o-2024-08-06"` - - `item_id: string` + - `"gpt-4o-2024-05-13"` - The ID of the MCP tool call item that completed. + - `"gpt-4o-audio-preview"` - - `output_index: number` + - `"gpt-4o-audio-preview-2024-10-01"` - The index of the output item that completed. + - `"gpt-4o-audio-preview-2024-12-17"` - - `sequence_number: number` + - `"gpt-4o-audio-preview-2025-06-03"` - The sequence number of this event. + - `"gpt-4o-mini-audio-preview"` - - `type: "response.mcp_call.completed"` + - `"gpt-4o-mini-audio-preview-2024-12-17"` - The type of the event. Always 'response.mcp_call.completed'. + - `"gpt-4o-search-preview"` - - `"response.mcp_call.completed"` + - `"gpt-4o-mini-search-preview"` - - `agent: optional object { agent_name }` + - `"gpt-4o-search-preview-2025-03-11"` - The agent that owns this multi-agent streaming event. + - `"gpt-4o-mini-search-preview-2025-03-11"` - - `agent_name: string` + - `"chatgpt-4o-latest"` - The canonical name of the agent that produced this item. + - `"codex-mini-latest"` - - `BetaResponseMcpCallFailedEvent object { item_id, output_index, sequence_number, 2 more }` + - `"gpt-4o-mini"` - Emitted when an MCP tool call has failed. + - `"gpt-4o-mini-2024-07-18"` - - `item_id: string` + - `"gpt-4-turbo"` - The ID of the MCP tool call item that failed. + - `"gpt-4-turbo-2024-04-09"` - - `output_index: number` + - `"gpt-4-0125-preview"` - The index of the output item that failed. + - `"gpt-4-turbo-preview"` - - `sequence_number: number` + - `"gpt-4-1106-preview"` - The sequence number of this event. + - `"gpt-4-vision-preview"` - - `type: "response.mcp_call.failed"` + - `"gpt-4"` - The type of the event. Always 'response.mcp_call.failed'. + - `"gpt-4-0314"` - - `"response.mcp_call.failed"` + - `"gpt-4-0613"` - - `agent: optional object { agent_name }` + - `"gpt-4-32k"` - The agent that owns this multi-agent streaming event. + - `"gpt-4-32k-0314"` - - `agent_name: string` + - `"gpt-4-32k-0613"` - The canonical name of the agent that produced this item. + - `"gpt-3.5-turbo"` - - `BetaResponseMcpCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + - `"gpt-3.5-turbo-16k"` - Emitted when an MCP tool call is in progress. + - `"gpt-3.5-turbo-0301"` - - `item_id: string` + - `"gpt-3.5-turbo-0613"` - The unique identifier of the MCP tool call item being processed. + - `"gpt-3.5-turbo-1106"` - - `output_index: number` + - `"gpt-3.5-turbo-0125"` - The index of the output item in the response's output array. + - `"gpt-3.5-turbo-16k-0613"` - - `sequence_number: number` + - `"o1-pro"` - The sequence number of this event. + - `"o1-pro-2025-03-19"` - - `type: "response.mcp_call.in_progress"` + - `"o3-pro"` - The type of the event. Always 'response.mcp_call.in_progress'. + - `"o3-pro-2025-06-10"` - - `"response.mcp_call.in_progress"` + - `"o3-deep-research"` - - `agent: optional object { agent_name }` + - `"o3-deep-research-2025-06-26"` - The agent that owns this multi-agent streaming event. + - `"o4-mini-deep-research"` - - `agent_name: string` + - `"o4-mini-deep-research-2025-06-26"` - The canonical name of the agent that produced this item. + - `"computer-use-preview"` - - `BetaResponseMcpListToolsCompletedEvent object { item_id, output_index, sequence_number, 2 more }` + - `"computer-use-preview-2025-03-11"` - Emitted when the list of available MCP tools has been successfully retrieved. + - `"gpt-5-codex"` - - `item_id: string` + - `"gpt-5-pro"` - The ID of the MCP tool call item that produced this output. + - `"gpt-5-pro-2025-10-06"` - - `output_index: number` + - `"gpt-5.1-codex-max"` - The index of the output item that was processed. + - `string` - - `sequence_number: number` + - `object: "response"` - The sequence number of this event. + The object type of this resource - always set to `response`. - - `type: "response.mcp_list_tools.completed"` + - `"response"` - The type of the event. Always 'response.mcp_list_tools.completed'. + - `output: array of BetaResponseOutputItem` - - `"response.mcp_list_tools.completed"` + An array of content items generated by the model. - - `agent: optional object { agent_name }` + - 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. - The agent that owns this multi-agent streaming event. + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - - `agent_name: string` + An output message from the model. - The canonical name of the agent that produced this item. + - `FileSearchCall object { id, queries, status, 3 more }` - - `BetaResponseMcpListToolsFailedEvent object { item_id, output_index, sequence_number, 2 more }` + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - Emitted when the attempt to list available MCP tools has failed. + - `id: string` - - `item_id: string` + The unique ID of the file search tool call. - The ID of the MCP tool call item that failed. + - `queries: array of string` - - `output_index: number` + The queries used to search for files. - The index of the output item that failed. + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `sequence_number: number` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - The sequence number of this event. + - `"in_progress"` - - `type: "response.mcp_list_tools.failed"` + - `"searching"` - The type of the event. Always 'response.mcp_list_tools.failed'. + - `"completed"` - - `"response.mcp_list_tools.failed"` + - `"incomplete"` - - `agent: optional object { agent_name }` + - `"failed"` - The agent that owns this multi-agent streaming event. + - `type: "file_search_call"` - - `agent_name: string` + The type of the file search tool call. Always `file_search_call`. - The canonical name of the agent that produced this item. + - `"file_search_call"` - - `BetaResponseMcpListToolsInProgressEvent object { item_id, output_index, sequence_number, 2 more }` + - `agent: optional object { agent_name }` - Emitted when the system is in the process of retrieving the list of available MCP tools. + The agent that produced this item. - - `item_id: string` + - `agent_name: string` - The ID of the MCP tool call item that is being processed. + The canonical name of the agent that produced this item. - - `output_index: number` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - The index of the output item that is being processed. + The results of the file search tool call. - - `sequence_number: number` + - `attributes: optional map[string or number or boolean]` - The sequence number of this event. + 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. - - `type: "response.mcp_list_tools.in_progress"` + - `string` - The type of the event. Always 'response.mcp_list_tools.in_progress'. + - `number` - - `"response.mcp_list_tools.in_progress"` + - `boolean` - - `agent: optional object { agent_name }` + - `file_id: optional string` - The agent that owns this multi-agent streaming event. + The unique ID of the file. - - `agent_name: string` + - `filename: optional string` - The canonical name of the agent that produced this item. + The name of the file. - - `BetaResponseOutputTextAnnotationAddedEvent object { annotation, annotation_index, content_index, 5 more }` + - `score: optional number` - Emitted when an annotation is added to output text content. + The relevance score of the file - a value between 0 and 1. - - `annotation: unknown` + - `text: optional string` - The annotation object being added. (See annotation schema for details.) + The text that was retrieved from the file. - - `annotation_index: number` + - `FunctionCall object { arguments, call_id, name, 6 more }` - The index of the annotation within the content part. + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `content_index: number` + - `arguments: string` - The index of the content part within the output item. + A JSON string of the arguments to pass to the function. - - `item_id: string` + - `call_id: string` - The unique identifier of the item to which the annotation is being added. + The unique ID of the function tool call generated by the model. - - `output_index: number` + - `name: string` - The index of the output item in the response's output array. + The name of the function to run. - - `sequence_number: number` + - `type: "function_call"` - The sequence number of this event. + The type of the function tool call. Always `function_call`. - - `type: "response.output_text.annotation.added"` + - `"function_call"` - The type of the event. Always 'response.output_text.annotation.added'. + - `id: optional string` - - `"response.output_text.annotation.added"` + The unique ID of the function tool call. - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. - - `BetaResponseQueuedEvent object { response, sequence_number, type, agent }` - - Emitted when a response is queued and waiting to be processed. + - `caller: optional object { type } or object { caller_id, type }` - - `response: BetaResponse` + The execution context that produced this tool call. - The full response object that is queued. + - `Direct object { type }` - - `sequence_number: number` + - `type: "direct"` - The sequence number for this event. + - `"direct"` - - `type: "response.queued"` + - `Program object { caller_id, type }` - The type of the event. Always 'response.queued'. + - `caller_id: string` - - `"response.queued"` + The call ID of the program item that produced this tool call. - - `agent: optional object { agent_name }` + - `type: "program"` - The agent that owns this multi-agent streaming event. + - `"program"` - - `agent_name: string` + - `namespace: optional string` - The canonical name of the agent that produced this item. + The namespace of the function to run. - - `BetaResponseCustomToolCallInputDeltaEvent object { delta, item_id, output_index, 3 more }` + - `status: optional "in_progress" or "completed" or "incomplete"` - Event representing a delta (partial update) to the input of a custom tool call. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `delta: string` + - `"in_progress"` - The incremental input data (delta) for the custom tool call. + - `"completed"` - - `item_id: string` + - `"incomplete"` - Unique identifier for the API item associated with this event. + - `FunctionCallOutput object { id, call_id, output, 5 more }` - - `output_index: number` + - `id: string` - The index of the output this delta applies to. + The unique ID of the function call tool output. - - `sequence_number: number` + - `call_id: string` - The sequence number of this event. + The unique ID of the function tool call generated by the model. - - `type: "response.custom_tool_call_input.delta"` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The event type identifier. + The output from the function call generated by your code. + Can be a string or an list of output content. - - `"response.custom_tool_call_input.delta"` + - `StringOutput = string` - - `agent: optional object { agent_name }` + A string of the output of the function call. - The agent that owns this multi-agent streaming event. + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `agent_name: string` + Text, image, or file output of the function call. - The canonical name of the agent that produced this item. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `BetaResponseCustomToolCallInputDoneEvent object { input, item_id, output_index, 3 more }` + A text input to the model. - Event indicating that input for a custom tool call is complete. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `input: string` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - The complete input data for the custom tool call. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `item_id: string` + A file input to the model. - Unique identifier for the API item associated with this event. + - `status: "in_progress" or "completed" or "incomplete"` - - `output_index: number` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The index of the output this event applies to. + - `"in_progress"` - - `sequence_number: number` + - `"completed"` - The sequence number of this event. + - `"incomplete"` - - `type: "response.custom_tool_call_input.done"` + - `type: "function_call_output"` - The event type identifier. + The type of the function tool call output. Always `function_call_output`. - - `"response.custom_tool_call_input.done"` + - `"function_call_output"` - `agent: optional object { agent_name }` - The agent that owns this multi-agent streaming event. + The agent that produced this item. - `agent_name: string` The canonical name of the agent that produced this item. - - `BetaResponseInjectCreatedEvent object { response_id, sequence_number, type, stream_id }` - - Emitted when all injected input items were validated and committed to the - active response. - - - `response_id: string` - - The ID of the response that accepted the input. - - - `sequence_number: number` + - `caller: optional object { type } or object { caller_id, type }` - The sequence number for this event. + The execution context that produced this tool call. - - `type: "response.inject.created"` + - `Direct object { type }` - The event discriminator. Always `response.inject.created`. + - `type: "direct"` - - `"response.inject.created"` + The caller type. Always `direct`. - - `stream_id: optional string` + - `"direct"` - The multiplexed WebSocket stream that emitted the event. This field is - present only when WebSocket multiplexing is enabled separately. + - `Program object { caller_id, type }` - - `BetaResponseInjectFailedEvent object { error, input, response_id, 3 more }` + - `caller_id: string` - Emitted when injected input could not be committed to a response. The event - returns the uncommitted raw input so the client can retry it in another - response when appropriate. + The call ID of the program item that produced this tool call. - - `error: object { code, message }` + - `type: "program"` - Information about why the input was not committed. + The caller type. Always `program`. - - `code: "response_already_completed" or "response_not_found"` + - `"program"` - A machine-readable error code. + - `created_by: optional string` - - `"response_already_completed"` + The identifier of the actor that created the item. - - `"response_not_found"` + - `AgentMessage object { id, author, content, 3 more }` - - `message: string` + - `id: string` - A human-readable description of the error. + The unique ID of the agent message. - - `input: array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + - `author: string` - The raw input items that were not committed. + The sending agent identity. - - `BetaEasyInputMessage object { content, role, phase, type }` + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 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. + Encrypted content sent between agents. - - `Message object { content, role, agent, 2 more }` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - 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 text input to the model. - - `content: BetaResponseInputMessageContentList` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - A list of one or many input items to the model, containing different content - types. + A text output from the model. - - `role: "user" or "system" or "developer"` + - `Text object { text, type }` - The role of the message input. One of `user`, `system`, or `developer`. + A text content. - - `"user"` + - `text: string` - - `"system"` + - `type: "text"` - - `"developer"` + - `"text"` - - `agent: optional object { agent_name }` + - `SummaryText object { text, type }` - The agent that produced this item. + A summary text from the model. - - `agent_name: string` + - `text: string` - The canonical name of the agent that produced this item. + A summary of the reasoning output from the model so far. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `type: "summary_text"` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The type of the object. Always `summary_text`. - - `"in_progress"` + - `"summary_text"` - - `"completed"` + - `ReasoningText object { text, type }` - - `"incomplete"` + Reasoning text from the model. - - `type: optional "message"` + - `text: string` - The type of the message input. Always set to `message`. + The reasoning text from the model. - - `"message"` + - `type: "reasoning_text"` - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + The type of the reasoning text. Always `reasoning_text`. - An output message from the model. + - `"reasoning_text"` - - `FileSearchCall object { id, queries, status, 3 more }` + - `BetaResponseOutputRefusal object { refusal, type }` - The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + A refusal from the model. - - `id: string` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - The unique ID of the file search tool call. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `queries: array of string` + - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` - The queries used to search for files. + A screenshot of a computer. - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `detail: "low" or "high" or "auto" or "original"` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"in_progress"` + - `"low"` - - `"searching"` + - `"high"` - - `"completed"` + - `"auto"` - - `"incomplete"` + - `"original"` - - `"failed"` + - `file_id: string` - - `type: "file_search_call"` + The identifier of an uploaded file that contains the screenshot. - The type of the file search tool call. Always `file_search_call`. + - `image_url: string` - - `"file_search_call"` + The URL of the screenshot image. - - `agent: optional object { agent_name }` + - `type: "computer_screenshot"` - The agent that produced this item. + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `agent_name: string` + - `"computer_screenshot"` - The canonical name of the agent that produced this item. + - `prompt_cache_breakpoint: optional object { mode }` - - `results: optional array of object { attributes, file_id, filename, 2 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 results of the file search tool call. + - `mode: "explicit"` - - `attributes: optional map[string or number or boolean]` + The breakpoint mode. Always `explicit`. - 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. + - `"explicit"` - - `string` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `number` + A file input to the model. - - `boolean` + - `EncryptedContent object { encrypted_content, type }` - - `file_id: optional string` + Opaque encrypted content that Responses API decrypts inside trusted model execution. - The unique ID of the file. + - `encrypted_content: string` - - `filename: optional string` + Opaque encrypted content. - The name of the file. + - `type: "encrypted_content"` - - `score: optional number` + The type of the input item. Always `encrypted_content`. - The relevance score of the file - a value between 0 and 1. + - `"encrypted_content"` - - `text: optional string` + - `recipient: string` - The text that was retrieved from the file. + The destination agent identity. - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + - `type: "agent_message"` - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + The type of the item. Always `agent_message`. - - `id: string` + - `"agent_message"` - The unique ID of the computer call. + - `agent: optional object { agent_name }` - - `call_id: string` + The agent that produced this item. - An identifier used when responding to the tool call with output. + - `agent_name: string` - - `pending_safety_checks: array of object { id, code, message }` + The canonical name of the agent that produced this item. - The pending safety checks for the computer call. + - `MultiAgentCall object { id, action, arguments, 3 more }` - `id: string` - The ID of the pending safety check. - - - `code: optional string` + The unique ID of the multi-agent call item. - The type of the pending safety check. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `message: optional string` + The multi-agent action to execute. - Details about the pending safety check. + - `"spawn_agent"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"interrupt_agent"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"list_agents"` - - `"in_progress"` + - `"send_message"` - - `"completed"` + - `"followup_task"` - - `"incomplete"` + - `"wait_agent"` - - `type: "computer_call"` + - `arguments: string` - The type of the computer call. Always `computer_call`. + The JSON string of arguments generated for the action. - - `"computer_call"` + - `call_id: string` - - `action: optional BetaComputerAction` + The unique ID linking this call to its output. - A click action. + - `type: "multi_agent_call"` - - `actions: optional BetaComputerActionList` + The type of the multi-agent call. Always `multi_agent_call`. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `"multi_agent_call"` - `agent: optional object { agent_name }` @@ -195025,61 +196202,63 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `ComputerCallOutput object { call_id, output, type, 4 more }` + - `MultiAgentCallOutput object { id, action, call_id, 3 more }` - The output of a computer tool call. + - `id: string` - - `call_id: string` + The unique ID of the multi-agent call output item. - The ID of the computer tool call that produced the output. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `output: BetaResponseComputerToolCallOutputScreenshot` + The multi-agent action that produced this result. - A computer screenshot image used with the computer use tool. + - `"spawn_agent"` - - `type: "computer_call_output"` + - `"interrupt_agent"` - The type of the computer tool call output. Always `computer_call_output`. + - `"list_agents"` - - `"computer_call_output"` + - `"send_message"` - - `id: optional string` + - `"followup_task"` - The ID of the computer tool call output. + - `"wait_agent"` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `call_id: string` - The safety checks reported by the API that have been acknowledged by the developer. + The unique ID of the multi-agent call. - - `id: string` + - `output: array of BetaResponseOutputText` - The ID of the pending safety check. + Text output returned by the multi-agent action. - - `code: optional string` + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - The type of the pending safety check. + The annotations of the text output. - - `message: optional string` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - Details about the pending safety check. + - `text: string` - - `agent: optional object { agent_name }` + The text output from the model. - The agent that produced this item. + - `type: "output_text"` - - `agent_name: string` + The type of the output text. Always `output_text`. - The canonical name of the agent that produced this item. + - `type: "multi_agent_call_output"` - - `status: optional "in_progress" or "completed" or "incomplete"` + The type of the multi-agent result. Always `multi_agent_call_output`. - The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. + - `"multi_agent_call_output"` - - `"in_progress"` + - `agent: optional object { agent_name }` - - `"completed"` + The agent that produced this item. - - `"incomplete"` + - `agent_name: string` + + The canonical name of the agent that produced this item. - `WebSearchCall object { id, action, status, 2 more }` @@ -195185,66 +196364,36 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `FunctionCall object { arguments, call_id, name, 6 more }` + - `ComputerCall object { id, call_id, pending_safety_checks, 5 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. - - - `name: string` - - The name of the function to run. - - - `type: "function_call"` - - The type of the function tool call. Always `function_call`. - - - `"function_call"` - - - `id: optional string` - - The unique ID of the function tool call. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. - - - `Direct object { type }` - - - `type: "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` - - `"program"` + The type of the pending safety check. - - `namespace: optional string` + - `message: optional string` - The namespace of the function to run. + Details about the pending safety check. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `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. @@ -195255,47 +196404,20 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `FunctionCallOutput object { call_id, output, type, 4 more }` - - The output of a function tool call. - - - `call_id: string` - - The unique ID of the function tool call generated by the model. - - - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - - Text, image, or file output of the function tool call. - - - `string` - - A JSON string of the output of the function tool call. - - - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - - An array of content outputs (text, image, file) for the function tool call. - - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](/docs/guides/vision) - - - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` + - `type: "computer_call"` - A file input to the model. + The type of the computer call. Always `computer_call`. - - `type: "function_call_output"` + - `"computer_call"` - The type of the function tool call output. Always `function_call_output`. + - `action: optional BetaComputerAction` - - `"function_call_output"` + A click action. - - `id: optional string` + - `actions: optional BetaComputerActionList` - The unique ID of the function 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. - `agent: optional object { agent_name }` @@ -195305,87 +196427,55 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `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 }` + - `ComputerCallOutput object { id, call_id, output, 5 more }` - - `caller_id: string` + - `id: string` - The call ID of the program item that produced this tool call. + The unique ID of the computer call tool output. - - `type: "program"` + - `call_id: string` - The caller type. Always `program`. + The ID of the computer tool call that produced the output. - - `"program"` + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `status: optional "in_progress" or "completed" or "incomplete"` + A computer screenshot image used with the computer use tool. - The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - - `"in_progress"` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - `"completed"` - `"incomplete"` - - `AgentMessage object { author, content, recipient, 3 more }` - - A message routed between agents. - - - `author: string` - - The sending agent identity. - - - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - - Plaintext, image, or encrypted content sent between agents. - - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](/docs/guides/vision) - - - `EncryptedContent object { encrypted_content, type }` - - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `"failed"` - - `encrypted_content: string` + - `"in_progress"` - Opaque encrypted content. + - `type: "computer_call_output"` - - `type: "encrypted_content"` + The type of the computer tool call output. Always `computer_call_output`. - The type of the input item. Always `encrypted_content`. + - `"computer_call_output"` - - `"encrypted_content"` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `recipient: string` + The safety checks reported by the API that have been acknowledged by the + developer. - The destination agent identity. + - `id: string` - - `type: "agent_message"` + The ID of the pending safety check. - The item type. Always `agent_message`. + - `code: optional string` - - `"agent_message"` + The type of the pending safety check. - - `id: optional string` + - `message: optional string` - The unique ID of this agent message item. + Details about the pending safety check. - `agent: optional object { agent_name }` @@ -195395,41 +196485,40 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `MultiAgentCall object { action, arguments, call_id, 3 more }` - - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - The multi-agent action that was executed. + - `created_by: optional string` - - `"spawn_agent"` + The identifier of the actor that created the item. - - `"interrupt_agent"` + - `Reasoning object { id, summary, type, 4 more }` - - `"list_agents"` + 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). - - `"send_message"` + - `id: string` - - `"followup_task"` + The unique identifier of the reasoning content. - - `"wait_agent"` + - `summary: array of object { text, type }` - - `arguments: string` + Reasoning summary content. - The action arguments as a JSON string. + - `text: string` - - `call_id: string` + A summary of the reasoning output from the model so far. - The unique ID linking this call to its output. + - `type: "summary_text"` - - `type: "multi_agent_call"` + The type of the object. Always `summary_text`. - The item type. Always `multi_agent_call`. + - `"summary_text"` - - `"multi_agent_call"` + - `type: "reasoning"` - - `id: optional string` + The type of the object. Always `reasoning`. - The unique ID of this multi-agent call. + - `"reasoning"` - `agent: optional object { agent_name }` @@ -195439,152 +196528,143 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `MultiAgentCallOutput object { action, call_id, output, 3 more }` - - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - The multi-agent action that produced this result. - - - `"spawn_agent"` - - - `"interrupt_agent"` + - `content: optional array of object { text, type }` - - `"list_agents"` + Reasoning text content. - - `"send_message"` + - `text: string` - - `"followup_task"` + The reasoning text from the model. - - `"wait_agent"` + - `type: "reasoning_text"` - - `call_id: string` + The type of the reasoning text. Always `reasoning_text`. - The unique ID of the multi-agent call. + - `"reasoning_text"` - - `output: array of object { text, type, annotations }` + - `encrypted_content: optional string` - Text output returned by the multi-agent action. + 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. - - `text: string` + - `status: optional "in_progress" or "completed" or "incomplete"` - The text content. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `type: "output_text"` + - `"in_progress"` - The content type. Always `output_text`. + - `"completed"` - - `"output_text"` + - `"incomplete"` - - `annotations: optional 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 }` + - `Program object { id, call_id, code, 3 more }` - Citations associated with the text content. + - `id: string` - - `FileCitation object { file_id, filename, index, type }` + The unique ID of the program item. - - `file_id: string` + - `call_id: string` - The ID of the file. + The stable call ID of the program item. - - `filename: string` + - `code: string` - The filename of the file cited. + The JavaScript source executed by programmatic tool calling. - - `index: number` + - `fingerprint: string` - The index of the file in the list of files. + Opaque program replay fingerprint that must be round-tripped. - - `type: "file_citation"` + - `type: "program"` - The citation type. Always `file_citation`. + The type of the item. Always `program`. - - `"file_citation"` + - `"program"` - - `URLCitation object { end_index, start_index, title, 2 more }` + - `agent: optional object { agent_name }` - - `end_index: number` + The agent that produced this item. - The index of the last character of the citation in the message. + - `agent_name: string` - - `start_index: number` + The canonical name of the agent that produced this item. - The index of the first character of the citation in the message. + - `ProgramOutput object { id, call_id, result, 3 more }` - - `title: string` + - `id: string` - The title of the cited resource. + The unique ID of the program output item. - - `type: "url_citation"` + - `call_id: string` - The citation type. Always `url_citation`. + The call ID of the program item. - - `"url_citation"` + - `result: string` - - `url: string` + The result produced by the program item. - The URL of the cited resource. + - `status: "completed" or "incomplete"` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + The terminal status of the program output item. - - `container_id: string` + - `"completed"` - The ID of the container. + - `"incomplete"` - - `end_index: number` + - `type: "program_output"` - The index of the last character of the citation in the message. + The type of the item. Always `program_output`. - - `file_id: string` + - `"program_output"` - The ID of the container file. + - `agent: optional object { agent_name }` - - `filename: string` + The agent that produced this item. - The filename of the container file cited. + - `agent_name: string` - - `start_index: number` + The canonical name of the agent that produced this item. - The index of the first character of the citation in the message. + - `ToolSearchCall object { id, arguments, call_id, 5 more }` - - `type: "container_file_citation"` + - `id: string` - The citation type. Always `container_file_citation`. + The unique ID of the tool search call item. - - `"container_file_citation"` + - `arguments: unknown` - - `type: "multi_agent_call_output"` + Arguments used for the tool search call. - The item type. Always `multi_agent_call_output`. + - `call_id: string` - - `"multi_agent_call_output"` + The unique ID of the tool search call generated by the model. - - `id: optional string` + - `execution: "server" or "client"` - The unique ID of this multi-agent call output. + Whether tool search was executed by the server or by the client. - - `agent: optional object { agent_name }` + - `"server"` - The agent that produced this item. + - `"client"` - - `agent_name: string` + - `status: "in_progress" or "completed" or "incomplete"` - The canonical name of the agent that produced this item. + The status of the tool search call item that was recorded. - - `ToolSearchCall object { arguments, type, id, 4 more }` + - `"in_progress"` - - `arguments: unknown` + - `"completed"` - The arguments supplied to the tool search call. + - `"incomplete"` - `type: "tool_search_call"` - The item type. Always `tool_search_call`. + The type of the item. Always `tool_search_call`. - `"tool_search_call"` - - `id: optional string` - - The unique ID of this tool search call. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -195593,11 +196673,21 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `call_id: optional string` + - `created_by: optional string` + + The identifier of the actor that created the item. + + - `ToolSearchOutput object { id, call_id, execution, 5 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: optional "server" or "client"` + - `execution: "server" or "client"` Whether tool search was executed by the server or by the client. @@ -195605,9 +196695,9 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"client"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `status: "in_progress" or "completed" or "incomplete"` - The status of the tool search call. + The status of the tool search output item that was recorded. - `"in_progress"` @@ -195615,11 +196705,9 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `ToolSearchOutput object { tools, type, id, 4 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. + The loaded tool definitions returned by tool search. - `Function object { name, parameters, strict, 5 more }` @@ -196612,14 +197700,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "tool_search_output"` - The item type. Always `tool_search_output`. + The type of the item. Always `tool_search_output`. - `"tool_search_output"` - - `id: optional string` - - The unique ID of this tool search output. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -196628,39 +197712,39 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `call_id: optional string` - - The unique ID of the tool search call generated by the model. + - `created_by: optional string` - - `execution: optional "server" or "client"` + The identifier of the actor that created the item. - Whether tool search was executed by the server or by the client. + - `AdditionalTools object { id, role, tools, 2 more }` - - `"server"` + - `id: string` - - `"client"` + The unique ID of the additional tools item. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `role: "unknown" or "user" or "assistant" or 5 more` - The status of the tool search output. + The role that provided the additional tools. - - `"in_progress"` + - `"unknown"` - - `"completed"` + - `"user"` - - `"incomplete"` + - `"assistant"` - - `AdditionalTools object { role, tools, type, 2 more }` + - `"system"` - - `role: "developer"` + - `"critic"` - The role that provided the additional tools. Only `developer` is supported. + - `"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` - A list of additional tools made available at this item. + The additional tool definitions made available at this item. - `Function object { name, parameters, strict, 5 more }` @@ -197653,14 +198737,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "additional_tools"` - The item type. Always `additional_tools`. + The type of the item. Always `additional_tools`. - `"additional_tools"` - - `id: optional string` - - The unique ID of this additional tools item. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -197669,83 +198749,17 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `Reasoning object { id, summary, type, 4 more }` + - `Compaction object { id, encrypted_content, type, 2 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). + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - `id: string` - The unique identifier of the reasoning content. - - - `summary: array of object { text, type }` - - 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"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `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, agent }` - - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + The unique ID of the compaction item. - `encrypted_content: string` - The encrypted content of the compaction summary. + The encrypted content that was produced by compaction. - `type: "compaction"` @@ -197753,10 +198767,6 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"compaction"` - - `id: optional string` - - The ID of the compaction item. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -197765,6 +198775,10 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. + - `created_by: optional string` + + The identifier of the actor that created the item. + - `ImageGenerationCall object { id, result, status, 2 more }` An image generation request made by the model. @@ -197982,9 +198996,13 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"incomplete"` - - `ShellCall object { action, call_id, type, 5 more }` + - `ShellCall object { id, action, call_id, 6 more }` - A tool representing a request to execute one or more shell commands. + 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 }` @@ -197992,30 +199010,60 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `commands: array of string` - Ordered shell commands for the execution environment to run. - - - `max_output_length: optional number` + - `max_output_length: number` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + Optional maximum number of characters to return from each command. - - `timeout_ms: optional number` + - `timeout_ms: number` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + Optional timeout in milliseconds for the commands. - `call_id: string` The unique ID of the shell tool call generated by the model. + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + + Represents the use of a local environment to perform shell actions. + + - `BetaResponseLocalEnvironment object { type }` + + Represents the use of a local environment to perform shell actions. + + - `type: "local"` + + The environment type. Always `local`. + + - `"local"` + + - `BetaResponseContainerReference 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. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -198032,8 +199080,6 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "direct"` - The caller type. Always `direct`. - - `"direct"` - `Program object { caller_id, type }` @@ -198044,61 +199090,87 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "program"` - The caller type. Always `program`. - - `"program"` - - `environment: optional BetaLocalEnvironment or BetaContainerReference` + - `created_by: optional string` - The environment to execute the shell commands in. + The ID of the entity that created this tool call. - - `BetaLocalEnvironment object { type, skills }` + - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` - - `BetaContainerReference object { container_id, type }` + The output of a shell tool call that was emitted. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `id: string` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + The unique ID of the shell call output. Populated when this item is returned via API. - - `"in_progress"` + - `call_id: string` - - `"completed"` + The unique ID of the shell tool call generated by the model. - - `"incomplete"` + - `max_output_length: number` - - `ShellCallOutput object { call_id, output, type, 5 more }` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - The streamed output items emitted by a shell tool call. + - `output: array of object { outcome, stderr, stdout, created_by }` - - `call_id: string` + An array of shell call output contents - The unique ID of the shell tool call generated by the model. + - `outcome: object { type } or object { exit_code, type }` - - `output: array of BetaResponseFunctionShellCallOutputContent` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `Timeout object { type }` - - `outcome: object { type } or object { exit_code, type }` + Indicates that the shell call exceeded its configured time limit. - The exit or timeout outcome associated with this shell call. + - `type: "timeout"` + + The outcome type. Always `timeout`. + + - `"timeout"` + + - `Exit object { exit_code, type }` + + Indicates that the shell commands finished and returned an exit code. + + - `exit_code: number` + + Exit code from the shell process. + + - `type: "exit"` + + The outcome type. Always `exit`. + + - `"exit"` - `stderr: string` - Captured stderr output for the shell call. + The standard error output that was captured. - `stdout: string` - Captured stdout output for the shell call. + The standard output that was captured. - - `type: "shell_call_output"` + - `created_by: optional string` - The type of the item. Always `shell_call_output`. + The identifier of the actor that created the item. - - `"shell_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 shell 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"` - `agent: optional object { agent_name }` @@ -198116,8 +199188,6 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "direct"` - The caller type. Always `direct`. - - `"direct"` - `Program object { caller_id, type }` @@ -198128,27 +199198,19 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "program"` - The caller type. Always `program`. - - `"program"` - - `max_output_length: optional number` - - The maximum number of UTF-8 characters captured for this shell call's combined output. - - - `status: optional "in_progress" or "completed" or "incomplete"` - - The status of the shell call output. + - `created_by: optional string` - - `"in_progress"` + The identifier of the actor that created the item. - - `"completed"` + - `ApplyPatchCall object { id, call_id, operation, 5 more }` - - `"incomplete"` + A tool call that applies file diffs by creating, deleting, or updating files. - - `ApplyPatchCall object { call_id, operation, status, 4 more }` + - `id: string` - A tool call representing a request to create, delete, or update files using diff patches. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - `call_id: string` @@ -198156,55 +199218,55 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - The specific create, delete, or update instruction for the apply_patch tool call. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - `CreateFile object { diff, path, type }` - Instruction for creating a new file via the apply_patch tool. + Instruction describing how to create a file via the apply_patch tool. - `diff: string` - Unified diff content to apply when creating the file. + Diff to apply. - `path: string` - Path of the file to create relative to the workspace root. + Path of the file to create. - `type: "create_file"` - The operation type. Always `create_file`. + Create a new file with the provided diff. - `"create_file"` - `DeleteFile object { path, type }` - Instruction for deleting an existing file via the apply_patch tool. + Instruction describing how to delete a file via the apply_patch tool. - `path: string` - Path of the file to delete relative to the workspace root. + Path of the file to delete. - `type: "delete_file"` - The operation type. Always `delete_file`. + Delete the specified file. - `"delete_file"` - `UpdateFile object { diff, path, type }` - Instruction for updating an existing file via the apply_patch tool. + Instruction describing how to update a file via the apply_patch tool. - `diff: string` - Unified diff content to apply to the existing file. + Diff to apply. - `path: string` - Path of the file to update relative to the workspace root. + Path of the file to update. - `type: "update_file"` - The operation type. Always `update_file`. + Update an existing file with the provided diff. - `"update_file"` @@ -198222,10 +199284,6 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"apply_patch_call"` - - `id: optional string` - - The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -198242,8 +199300,6 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "direct"` - The caller type. Always `direct`. - - `"direct"` - `Program object { caller_id, type }` @@ -198254,13 +199310,19 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "program"` - The caller type. Always `program`. - - `"program"` - - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` + - `created_by: optional string` - The streamed output emitted by an apply patch tool call. + The ID of the entity that created this tool call. + + - `ApplyPatchCallOutput object { id, call_id, status, 5 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` @@ -198280,10 +199342,6 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"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. - - `agent: optional object { agent_name }` The agent that produced this item. @@ -198300,8 +199358,6 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "direct"` - The caller type. Always `direct`. - - `"direct"` - `Program object { caller_id, type }` @@ -198312,13 +199368,76 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `type: "program"` - The caller type. Always `program`. - - `"program"` + - `created_by: optional string` + + The ID of the entity that created this tool call output. + - `output: optional string` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + Optional textual output returned by the apply patch tool. + + - `McpCall object { id, arguments, name, 7 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"` + + - `agent: optional object { agent_name }` + + The agent that produced this item. + + - `agent_name: string` + + The canonical name of the agent that produced this item. + + - `approval_request_id: optional string` + + Unique identifier for the MCP tool call approval request. + Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. + + - `error: optional string` + + The error from the tool call, if any. + + - `output: optional string` + + The output from the tool call. + + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + + - `"in_progress"` + + - `"completed"` + + - `"incomplete"` + + - `"calling"` + + - `"failed"` - `McpListTools object { id, server_label, tools, 3 more }` @@ -198404,10 +199523,14 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The canonical name of the agent that produced this item. - - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` + - `McpApprovalResponse object { id, approval_request_id, approve, 3 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. @@ -198422,10 +199545,6 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"mcp_approval_response"` - - `id: optional string` - - The unique ID of the approval response - - `agent: optional object { agent_name }` The agent that produced this item. @@ -198438,142 +199557,6 @@ curl -X POST https://api.openai.com/v1/responses/compact \ Optional reason for the decision. - - `McpCall object { id, arguments, name, 7 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"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `approval_request_id: optional string` - - Unique identifier for the MCP tool call approval request. - Include this value in a subsequent `mcp_approval_response` input to approve or reject the corresponding tool call. - - - `error: optional string` - - The error from the tool call, if any. - - - `output: optional string` - - The output from the tool call. - - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - - `"in_progress"` - - - `"completed"` - - - `"incomplete"` - - - `"calling"` - - - `"failed"` - - - `CustomToolCallOutput object { call_id, output, type, 3 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. - - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - 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 BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - Text, image, or file output of the custom tool call. - - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - A text input to the model. - - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - An image input to the model. Learn about [image inputs](/docs/guides/vision). - - - `BetaResponseInputFile 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. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `caller: optional object { type } or object { caller_id, type }` - - The execution context that produced this tool call. - - - `Direct object { type }` - - - `type: "direct"` - - The caller type. Always `direct`. - - - `"direct"` - - - `Program object { caller_id, type }` - - - `caller_id: string` - - The call ID of the program item that produced this tool call. - - - `type: "program"` - - The caller type. Always `program`. - - - `"program"` - - `CustomToolCall object { call_id, input, name, 5 more }` A call to a custom tool created by the model. @@ -198632,257 +199615,110 @@ curl -X POST https://api.openai.com/v1/responses/compact \ The namespace of the custom tool being called. - - `CompactionTrigger object { type, agent }` - - Compacts the current context. Must be the final input item. - - - `type: "compaction_trigger"` - - The type of the item. Always `compaction_trigger`. - - - `"compaction_trigger"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `ItemReference object { id, agent, type }` - - An internal identifier for an item to reference. - - - `id: string` - - The ID of the item to reference. - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `type: optional "item_reference"` - - The type of item to reference. Always `item_reference`. - - - `"item_reference"` - - - `Program object { id, call_id, code, 3 more }` - - - `id: string` - - The unique ID of this program item. - - - `call_id: string` - - The stable call ID of the program item. - - - `code: string` - - The JavaScript source executed by programmatic tool calling. - - - `fingerprint: string` - - Opaque program replay fingerprint that must be round-tripped. - - - `type: "program"` - - The item type. Always `program`. - - - `"program"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `ProgramOutput object { id, call_id, result, 3 more }` + - `CustomToolCallOutput object { id, call_id, output, 5 more }` - `id: string` - The unique ID of this program output item. + The unique ID of the custom tool call output item. - `call_id: string` - The call ID of the program item. - - - `result: string` - - The result produced by the program item. - - - `status: "completed" or "incomplete"` - - The terminal status of the program output. - - - `"completed"` - - - `"incomplete"` - - - `type: "program_output"` - - The item type. Always `program_output`. - - - `"program_output"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `response_id: string` - - The ID of the response that rejected the input. - - - `sequence_number: number` - - The sequence number for this event. - - - `type: "response.inject.failed"` - - The event discriminator. Always `response.inject.failed`. - - - `"response.inject.failed"` - - - `stream_id: optional string` - - The multiplexed WebSocket stream that emitted the event. This field is - present only when WebSocket multiplexing is enabled separately. - -### Beta Skill Reference - -- `BetaSkillReference 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. - -### Beta Tool Choice Allowed - -- `BetaToolChoiceAllowed object { mode, tools, type }` - - Constrains the tools available to the model to a pre-defined set. - - - `mode: "auto" or "required"` - - Constrains the tools available to the model to a pre-defined set. - - `auto` allows the model to pick from among the allowed tools and generate a - message. - - `required` requires the model to call one or more of the allowed tools. + The call ID, used to map this custom tool call output to a custom tool call. - - `"auto"` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `"required"` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `tools: array of map[unknown]` + - `StringOutput = string` - A list of tool definitions that the model should be allowed to call. + A string of the output of the custom tool call. - For the Responses API, the list of tool definitions might look like: + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + Text, image, or file output of the custom tool call. - - `type: "allowed_tools"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - Allowed tool configuration type. Always `allowed_tools`. + A text input to the model. - - `"allowed_tools"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` -### Beta Tool Choice Apply Patch + An image input to the model. Learn about [image inputs](/docs/guides/vision). -- `BetaToolChoiceApplyPatch object { type }` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - Forces the model to call the apply_patch tool when executing a tool call. + A file input to the model. - - `type: "apply_patch"` + - `status: "in_progress" or "completed" or "incomplete"` - The tool to call. Always `apply_patch`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"apply_patch"` + - `"in_progress"` -### Beta Tool Choice Custom + - `"completed"` -- `BetaToolChoiceCustom object { name, type }` + - `"incomplete"` - Use this option to force the model to call a specific custom tool. + - `type: "custom_tool_call_output"` - - `name: string` + The type of the custom tool call output. Always `custom_tool_call_output`. - The name of the custom tool to call. + - `"custom_tool_call_output"` - - `type: "custom"` + - `agent: optional object { agent_name }` - For custom tool calling, the type is always `custom`. + The agent that produced this item. - - `"custom"` + - `agent_name: string` -### Beta Tool Choice Function + The canonical name of the agent that produced this item. -- `BetaToolChoiceFunction object { name, type }` + - `caller: optional object { type } or object { caller_id, type }` - Use this option to force the model to call a specific function. + The execution context that produced this tool call. - - `name: string` + - `Direct object { type }` - The name of the function to call. + - `type: "direct"` - - `type: "function"` + The caller type. Always `direct`. - For function calling, the type is always `function`. + - `"direct"` - - `"function"` + - `Program object { caller_id, type }` -### Beta Tool Choice Mcp + - `caller_id: string` -- `BetaToolChoiceMcp object { server_label, type, name }` + The call ID of the program item that produced this tool call. - Use this option to force the model to call a specific tool on a remote MCP server. + - `type: "program"` - - `server_label: string` + The caller type. Always `program`. - The label of the MCP server to use. + - `"program"` - - `type: "mcp"` + - `created_by: optional string` - For MCP tools, the type is always `mcp`. + The identifier of the actor that created the item. - - `"mcp"` + - `parallel_tool_calls: boolean` - - `name: optional string` + Whether to allow the model to run tool calls in parallel. - The name of the tool to call on the server. + - `temperature: number` -### Beta Tool Choice Options + 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. -- `BetaToolChoiceOptions = "none" or "auto" or "required"` + - `tool_choice: BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes 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 + the model can call. + + - `BetaToolChoiceOptions = "none" or "auto" or "required"` Controls which (if any) tool is called by the model. @@ -198899,21 +199735,44 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"required"` -### Beta Tool Choice Shell + - `BetaToolChoiceAllowed object { mode, tools, type }` -- `BetaToolChoiceShell object { type }` + Constrains the tools available to the model to a pre-defined set. - Forces the model to call the shell tool when a tool call is required. + - `mode: "auto" or "required"` - - `type: "shell"` + Constrains the tools available to the model to a pre-defined set. - The tool to call. Always `shell`. + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `"shell"` + `required` requires the model to call one or more of the allowed tools. -### Beta Tool Choice Types + - `"auto"` -- `BetaToolChoiceTypes object { type }` + - `"required"` + + - `tools: array of map[unknown]` + + A list of tool definitions that the model should be allowed to call. + + For the Responses API, the list of tool definitions might look like: + + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` + + - `type: "allowed_tools"` + + Allowed tool configuration type. Always `allowed_tools`. + + - `"allowed_tools"` + + - `BetaToolChoiceTypes object { type }` Indicates that the model should use a built-in tool to generate a response. [Learn more about built-in tools](/docs/guides/tools). @@ -198949,3645 +199808,3681 @@ curl -X POST https://api.openai.com/v1/responses/compact \ - `"code_interpreter"` -# Input Items + - `BetaToolChoiceFunction object { name, type }` -## List input items + Use this option to force the model to call a specific function. -**get** `/responses/{response_id}/input_items?beta=true` + - `name: string` -Returns a list of input items for a given response. + The name of the function to call. -### Path Parameters + - `type: "function"` -- `response_id: string` + For function calling, the type is always `function`. -### Query Parameters + - `"function"` -- `after: optional string` + - `BetaToolChoiceMcp object { server_label, type, name }` - An item ID to list items after, used in pagination. + Use this option to force the model to call a specific tool on a remote MCP server. -- `include: optional array of BetaResponseIncludable` + - `server_label: string` - Additional fields to include in the response. See the `include` - parameter for Response creation above for more information. + The label of the MCP server to use. - - `"file_search_call.results"` + - `type: "mcp"` - - `"web_search_call.results"` + For MCP tools, the type is always `mcp`. - - `"web_search_call.action.sources"` + - `"mcp"` - - `"message.input_image.image_url"` + - `name: optional string` - - `"computer_call_output.output.image_url"` + The name of the tool to call on the server. - - `"code_interpreter_call.outputs"` + - `BetaToolChoiceCustom object { name, type }` - - `"reasoning.encrypted_content"` + Use this option to force the model to call a specific custom tool. - - `"message.output_text.logprobs"` + - `name: string` -- `limit: optional number` + The name of the custom tool to call. - A limit on the number of objects to be returned. Limit can range between - 1 and 100, and the default is 20. + - `type: "custom"` -- `order: optional "asc" or "desc"` + For custom tool calling, the type is always `custom`. - The order to return the input items in. Default is `desc`. + - `"custom"` - - `asc`: Return the input items in ascending order. - - `desc`: Return the input items in descending order. + - `BetaSpecificProgrammaticToolCallingParam object { type }` - - `"asc"` + - `type: "programmatic_tool_calling"` - - `"desc"` + The tool to call. Always `programmatic_tool_calling`. -### Header Parameters + - `"programmatic_tool_calling"` -- `"openai-beta": optional array of "responses_multi_agent=v1"` + - `BetaToolChoiceApplyPatch object { type }` - - `"responses_multi_agent=v1"` + Forces the model to call the apply_patch tool when executing a tool call. -### Returns + - `type: "apply_patch"` -- `BetaResponseItemList object { data, first_id, has_more, 2 more }` + The tool to call. Always `apply_patch`. - A list of Response items. + - `"apply_patch"` - - `data: array of BetaResponseInputMessageItem or BetaResponseOutputMessage or object { id, queries, status, 3 more } or 29 more` + - `BetaToolChoiceShell object { type }` - A list of items used to generate this response. + Forces the model to call the shell tool when a tool call is required. - - `BetaResponseInputMessageItem object { id, content, role, 3 more }` + - `type: "shell"` - - `id: string` + The tool to call. Always `shell`. - The unique ID of the message input. + - `"shell"` - - `content: BetaResponseInputMessageContentList` + - `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 one or many input items to the model, containing different content - types. + 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. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + We support the following categories of tools: - A text input to the model. + - **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. - - `text: string` + - `Function object { name, parameters, strict, 5 more }` - The text input to the model. + Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). - - `type: "input_text"` + - `name: string` - The type of the input item. Always `input_text`. + The name of the function to call. - - `"input_text"` + - `parameters: map[unknown]` - - `prompt_cache_breakpoint: optional object { mode }` + A JSON schema object describing the parameters of the function. - 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. + - `strict: boolean` - - `mode: "explicit"` + Whether strict parameter validation is enforced for this function tool. - The breakpoint mode. Always `explicit`. + - `type: "function"` - - `"explicit"` + The type of the function tool. Always `function`. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `"function"` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `allowed_callers: optional array of "direct" or "programmatic"` - - `detail: "low" or "high" or "auto" or "original"` + The tool invocation context(s). - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `"direct"` - - `"low"` + - `"programmatic"` - - `"high"` + - `defer_loading: optional boolean` - - `"auto"` + Whether this function is deferred and loaded via tool search. - - `"original"` + - `description: optional string` - - `type: "input_image"` + A description of the function. Used by the model to determine whether or not to call the function. - The type of the input item. Always `input_image`. + - `output_schema: optional map[unknown]` - - `"input_image"` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `file_id: optional string` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - The ID of the file to be sent to the model. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `image_url: optional string` + - `type: "file_search"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The type of the file search tool. Always `file_search`. - - `prompt_cache_breakpoint: optional object { mode }` + - `"file_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. + - `vector_store_ids: array of string` - - `mode: "explicit"` + The IDs of the vector stores to search. - The breakpoint mode. Always `explicit`. + - `filters: optional object { key, type, value } or object { filters, type }` - - `"explicit"` + A filter to apply. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `ComparisonFilter object { key, type, value }` - A file input to the model. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `type: "input_file"` + - `key: string` - The type of the input item. Always `input_file`. + The key to compare against the value. - - `"input_file"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `detail: optional "auto" or "low" or "high"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - 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`. + - `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 - - `"auto"` + - `"eq"` - - `"low"` + - `"ne"` - - `"high"` + - `"gt"` - - `file_data: optional string` + - `"gte"` - The content of the file to be sent to the model. + - `"lt"` - - `file_id: optional string` + - `"lte"` - The ID of the file to be sent to the model. + - `"in"` - - `file_url: optional string` + - `"nin"` - The URL of the file to be sent to the model. + - `value: string or number or boolean or array of string or number` - - `filename: optional string` + The value to compare against the attribute key; supports string, number, or boolean types. - The name of the file to be sent to the model. + - `string` - - `prompt_cache_breakpoint: optional object { mode }` + - `number` - 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. + - `boolean` - - `mode: "explicit"` + - `array of string or number` - The breakpoint mode. Always `explicit`. + - `string` - - `"explicit"` + - `number` - - `role: "user" or "system" or "developer"` + - `CompoundFilter object { filters, type }` - The role of the message input. One of `user`, `system`, or `developer`. + Combine multiple filters using `and` or `or`. - - `"user"` + - `filters: array of object { key, type, value } or unknown` - - `"system"` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `"developer"` + - `ComparisonFilter object { key, type, value }` - - `type: "message"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The type of the message input. Always set to `message`. + - `key: string` - - `"message"` + The key to compare against the value. - - `agent: optional object { agent_name }` + - `type: "eq" or "ne" or "gt" or 5 more` - The agent that produced this item. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `agent_name: string` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - The canonical name of the agent that produced this item. + - `"eq"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"ne"` - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"gt"` - - `"in_progress"` + - `"gte"` - - `"completed"` + - `"lt"` - - `"incomplete"` + - `"lte"` - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + - `"in"` - An output message from the model. + - `"nin"` - - `id: string` + - `value: string or number or boolean or array of string or number` - The unique ID of the output message. + The value to compare against the attribute key; supports string, number, or boolean types. - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `string` - The content of the output message. + - `number` - - `BetaResponseOutputText object { annotations, logprobs, text, type }` + - `boolean` - A text output from the model. + - `array of string or number` - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + - `string` - The annotations of the text output. + - `number` - - `FileCitation object { file_id, filename, index, type }` + - `unknown` - A citation to a file. + - `type: "and" or "or"` - - `file_id: string` + Type of operation: `and` or `or`. - The ID of the file. + - `"and"` - - `filename: string` + - `"or"` - The filename of the file cited. + - `max_num_results: optional number` - - `index: number` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - The index of the file in the list of files. + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `type: "file_citation"` + Ranking options for search. - The type of the file citation. Always `file_citation`. + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `"file_citation"` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `URLCitation object { end_index, start_index, title, 2 more }` + - `embedding_weight: number` - A citation for a web resource used to generate a model response. + The weight of the embedding in the reciprocal ranking fusion. - - `end_index: number` + - `text_weight: number` - The index of the last character of the URL citation in the message. + The weight of the text in the reciprocal ranking fusion. - - `start_index: number` + - `ranker: optional "auto" or "default-2024-11-15"` - The index of the first character of the URL citation in the message. + The ranker to use for the file search. - - `title: string` + - `"auto"` - The title of the web resource. + - `"default-2024-11-15"` - - `type: "url_citation"` + - `score_threshold: optional number` - The type of the URL citation. Always `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. - - `"url_citation"` + - `Computer object { type }` - - `url: string` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The URL of the web resource. + - `type: "computer"` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + The type of the computer tool. Always `computer`. - A citation for a container file used to generate a model response. + - `"computer"` - - `container_id: string` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - The ID of the container file. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `end_index: number` + - `display_height: number` - The index of the last character of the container file citation in the message. + The height of the computer display. - - `file_id: string` + - `display_width: number` - The ID of the file. + The width of the computer display. - - `filename: string` + - `environment: "windows" or "mac" or "linux" or 2 more` - The filename of the container file cited. + The type of computer environment to control. - - `start_index: number` + - `"windows"` - The index of the first character of the container file citation in the message. + - `"mac"` - - `type: "container_file_citation"` + - `"linux"` - The type of the container file citation. Always `container_file_citation`. + - `"ubuntu"` - - `"container_file_citation"` + - `"browser"` - - `FilePath object { file_id, index, type }` + - `type: "computer_use_preview"` - A path to a file. + The type of the computer use tool. Always `computer_use_preview`. - - `file_id: string` + - `"computer_use_preview"` - The ID of the file. + - `WebSearch object { type, filters, search_context_size, user_location }` - - `index: number` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - The index of the file in the list of files. + - `type: "web_search" or "web_search_2025_08_26"` - - `type: "file_path"` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - The type of the file path. Always `file_path`. + - `"web_search"` - - `"file_path"` + - `"web_search_2025_08_26"` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `filters: optional object { allowed_domains }` - - `token: string` + Filters for the search. - - `bytes: array of number` + - `allowed_domains: optional array of string` - - `logprob: number` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `top_logprobs: array of object { token, bytes, logprob }` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `token: string` + - `search_context_size: optional "low" or "medium" or "high"` - - `bytes: array of number` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `logprob: number` + - `"low"` - - `text: string` + - `"medium"` - The text output from the model. + - `"high"` - - `type: "output_text"` + - `user_location: optional object { city, country, region, 2 more }` - The type of the output text. Always `output_text`. + The approximate location of the user. - - `"output_text"` + - `city: optional string` - - `BetaResponseOutputRefusal object { refusal, type }` + Free text input for the city of the user, e.g. `San Francisco`. - A refusal from the model. + - `country: optional string` - - `refusal: string` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The refusal explanation from the model. + - `region: optional string` - - `type: "refusal"` + Free text input for the region of the user, e.g. `California`. - The type of the refusal. Always `refusal`. + - `timezone: optional string` - - `"refusal"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `role: "assistant"` + - `type: optional "approximate"` - The role of the output message. Always `assistant`. + The type of location approximation. Always `approximate`. - - `"assistant"` + - `"approximate"` - - `status: "in_progress" or "completed" or "incomplete"` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `"in_progress"` + - `server_label: string` - - `"completed"` + A label for this MCP server, used to identify it in tool calls. - - `"incomplete"` + - `type: "mcp"` - - `type: "message"` + The type of the MCP tool. Always `mcp`. - The type of the output message. Always `message`. + - `"mcp"` - - `"message"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `agent: optional object { agent_name }` + The tool invocation context(s). - The agent that produced this item. + - `"direct"` - - `agent_name: string` + - `"programmatic"` - The canonical name of the agent that produced this item. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `phase: optional "commentary" or "final_answer"` + List of allowed tool names or a filter object. - 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. + - `McpAllowedTools = array of string` - - `"commentary"` + A string array of allowed tool names - - `"final_answer"` + - `McpToolFilter object { read_only, tool_names }` - - `FileSearchCall object { id, queries, status, 3 more }` + A filter object to specify which tools are allowed. - The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) 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 file search tool call. + - `tool_names: optional array of string` - - `queries: array of string` + List of allowed tool names. - The queries used to search for files. + - `authorization: optional string` - - `status: "in_progress" or "searching" or "completed" or 2 more` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `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). - - `"searching"` + Currently supported `connector_id` values are: - - `"completed"` + - 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` - - `"incomplete"` + - `"connector_dropbox"` - - `"failed"` + - `"connector_gmail"` - - `type: "file_search_call"` + - `"connector_googlecalendar"` - The type of the file search tool call. Always `file_search_call`. + - `"connector_googledrive"` - - `"file_search_call"` + - `"connector_microsoftteams"` - - `agent: optional object { agent_name }` + - `"connector_outlookcalendar"` - The agent that produced this item. + - `"connector_outlookemail"` - - `agent_name: string` + - `"connector_sharepoint"` - The canonical name of the agent that produced this item. + - `defer_loading: optional boolean` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + Whether this MCP tool is deferred and discovered via tool search. - The results of the file search tool call. + - `headers: optional map[string]` - - `attributes: optional map[string or number or boolean]` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + - `require_approval: optional object { always, never } or "always" or "never"` - - `string` + Specify which of the MCP server's tools require approval. - - `number` + - `McpToolApprovalFilter object { always, never }` - - `boolean` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `file_id: optional string` + - `always: optional object { read_only, tool_names }` - The unique ID of the file. + A filter object to specify which tools are allowed. - - `filename: optional string` + - `read_only: optional boolean` - The name of the file. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `score: optional number` + - `tool_names: optional array of string` - The relevance score of the file - a value between 0 and 1. + List of allowed tool names. - - `text: optional string` + - `never: optional object { read_only, tool_names }` - The text that was retrieved from the file. + A filter object to specify which tools are allowed. - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + - `read_only: optional boolean` - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `id: string` + - `tool_names: optional array of string` - The unique ID of the computer call. + List of allowed tool names. - - `call_id: string` + - `McpToolApprovalSetting = "always" or "never"` - An identifier used when responding to the tool call with output. + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `pending_safety_checks: array of object { id, code, message }` + - `"always"` - The pending safety checks for the computer call. + - `"never"` - - `id: string` + - `server_description: optional string` - The ID of the pending safety check. + Optional description of the MCP server, used to provide more context. - - `code: optional string` + - `server_url: optional string` - The type of the pending safety check. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `message: optional string` + - `tunnel_id: optional string` - Details about the pending safety check. + 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. - - `status: "in_progress" or "completed" or "incomplete"` + - `CodeInterpreter object { container, type, allowed_callers }` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + A tool that runs Python code to help generate a response to a prompt. - - `"in_progress"` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `"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. - - `"incomplete"` + - `string` - - `type: "computer_call"` + The container ID. - The type of the computer call. Always `computer_call`. + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `"computer_call"` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `action: optional BetaComputerAction` + - `type: "auto"` - A click action. + Always `auto`. - - `Click object { button, type, x, 2 more }` + - `"auto"` - A click action. + - `file_ids: optional array of string` - - `button: "left" or "right" or "wheel" or 2 more` + An optional list of uploaded files to make available to your code. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `"left"` + The memory limit for the code interpreter container. - - `"right"` + - `"1g"` - - `"wheel"` + - `"4g"` - - `"back"` + - `"16g"` - - `"forward"` + - `"64g"` - - `type: "click"` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - Specifies the event type. For a click action, this property is always `click`. + Network access policy for the container. - - `"click"` + - `BetaContainerNetworkPolicyDisabled object { type }` - - `x: number` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - The x-coordinate where the click occurred. + - `type: "code_interpreter"` - - `y: number` + The type of the code interpreter tool. Always `code_interpreter`. - The y-coordinate where the click occurred. + - `"code_interpreter"` - - `keys: optional array of string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The keys being held while clicking. + The tool invocation context(s). - - `DoubleClick object { keys, type, x, y }` + - `"direct"` - A double click action. + - `"programmatic"` - - `keys: array of string` + - `ProgrammaticToolCalling object { type }` - The keys being held while double-clicking. + - `type: "programmatic_tool_calling"` - - `type: "double_click"` + The type of the tool. Always `programmatic_tool_calling`. - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `"programmatic_tool_calling"` - - `"double_click"` + - `ImageGeneration object { type, action, background, 9 more }` - - `x: number` + A tool that generates images using the GPT image models. - The x-coordinate where the double click occurred. + - `type: "image_generation"` - - `y: number` + The type of the image generation tool. Always `image_generation`. - The y-coordinate where the double click occurred. + - `"image_generation"` - - `Drag object { path, type, keys }` + - `action: optional "generate" or "edit" or "auto"` - A drag action. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `path: array of object { x, y }` + - `"generate"` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `"edit"` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `"auto"` - - `x: number` + - `background: optional "transparent" or "opaque" or "auto"` - The x-coordinate. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `y: number` + - `"transparent"` - The y-coordinate. + - `"opaque"` - - `type: "drag"` + - `"auto"` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `input_fidelity: optional "high" or "low"` - - `"drag"` + 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`. - - `keys: optional array of string` + - `"high"` - The keys being held while dragging the mouse. + - `"low"` - - `Keypress object { keys, type }` + - `input_image_mask: optional object { file_id, image_url }` - A collection of keypresses the model would like to perform. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `keys: array of string` + - `file_id: optional string` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + File ID for the mask image. - - `type: "keypress"` + - `image_url: optional string` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + Base64-encoded mask image. - - `"keypress"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `Move object { type, x, y, keys }` + The image generation model to use. Default: `gpt-image-1`. - A mouse move action. + - `string` - - `type: "move"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - Specifies the event type. For a move action, this property is always set to `move`. + The image generation model to use. Default: `gpt-image-1`. - - `"move"` + - `"gpt-image-1"` - - `x: number` + - `"gpt-image-1-mini"` - The x-coordinate to move to. + - `"gpt-image-1.5"` - - `y: number` + - `moderation: optional "auto" or "low"` - The y-coordinate to move to. + Moderation level for the generated image. Default: `auto`. - - `keys: optional array of string` + - `"auto"` - The keys being held while moving the mouse. + - `"low"` - - `Screenshot object { type }` + - `output_compression: optional number` - A screenshot action. + Compression level for the output image. Default: 100. - - `type: "screenshot"` + - `output_format: optional "png" or "webp" or "jpeg"` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `"screenshot"` + - `"png"` - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `"webp"` - A scroll action. + - `"jpeg"` - - `scroll_x: number` + - `partial_images: optional number` - The horizontal scroll distance. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `scroll_y: number` + - `quality: optional "low" or "medium" or "high" or "auto"` - The vertical scroll distance. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `type: "scroll"` + - `"low"` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `"medium"` - - `"scroll"` + - `"high"` - - `x: number` + - `"auto"` - The x-coordinate where the scroll occurred. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `y: number` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - The y-coordinate where the scroll occurred. + - `string` - - `keys: optional array of string` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - The keys being held while scrolling. + 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 object { text, type }` + - `"1024x1024"` - An action to type in text. + - `"1024x1536"` - - `text: string` + - `"1536x1024"` - The text to type. + - `"auto"` - - `type: "type"` + - `LocalShell object { type }` - Specifies the event type. For a type action, this property is always set to `type`. + A tool that allows the model to execute shell commands in a local environment. - - `"type"` + - `type: "local_shell"` - - `Wait object { type }` + The type of the local shell tool. Always `local_shell`. - A wait action. + - `"local_shell"` - - `type: "wait"` + - `Shell object { type, allowed_callers, environment }` - Specifies the event type. For a wait action, this property is always set to `wait`. + A tool that allows the model to execute shell commands. - - `"wait"` + - `type: "shell"` - - `actions: optional BetaComputerActionList` + The type of the shell tool. Always `shell`. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `"shell"` - - `Click object { button, type, x, 2 more }` + - `allowed_callers: optional array of "direct" or "programmatic"` - A click action. + The tool invocation context(s). - - `DoubleClick object { keys, type, x, y }` + - `"direct"` - A double click action. + - `"programmatic"` - - `Drag object { path, type, keys }` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - A drag action. + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `Keypress object { keys, type }` + - `BetaLocalEnvironment object { type, skills }` - A collection of keypresses the model would like to perform. + - `BetaContainerReference object { container_id, type }` - - `Move object { type, x, y, keys }` + - `Custom object { name, type, allowed_callers, 3 more }` - A mouse move action. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `Screenshot object { type }` + - `name: string` - A screenshot action. + The name of the custom tool, used to identify it in tool calls. - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `type: "custom"` - A scroll action. + The type of the custom tool. Always `custom`. - - `Type object { text, type }` + - `"custom"` - An action to type in text. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `Wait object { type }` + The tool invocation context(s). - A wait action. + - `"direct"` - - `agent: optional object { agent_name }` + - `"programmatic"` - The agent that produced this item. + - `defer_loading: optional boolean` - - `agent_name: string` + Whether this tool should be deferred and discovered via tool search. - The canonical name of the agent that produced this item. + - `description: optional string` - - `ComputerCallOutput object { id, call_id, output, 5 more }` + Optional description of the custom tool, used to provide more context. - - `id: string` + - `format: optional object { type } or object { definition, syntax, type }` - The unique ID of the computer call tool output. + The input format for the custom tool. Default is unconstrained text. - - `call_id: string` + - `Text object { type }` - The ID of the computer tool call that produced the output. + Unconstrained free-form text. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `type: "text"` - A computer screenshot image used with the computer use tool. + Unconstrained text format. Always `text`. - - `type: "computer_screenshot"` + - `"text"` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `Grammar object { definition, syntax, type }` - - `"computer_screenshot"` + A grammar defined by the user. - - `file_id: optional string` + - `definition: string` - The identifier of an uploaded file that contains the screenshot. + The grammar definition. - - `image_url: optional string` + - `syntax: "lark" or "regex"` - The URL of the screenshot image. + The syntax of the grammar definition. One of `lark` or `regex`. - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + - `"lark"` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `"regex"` - - `"completed"` + - `type: "grammar"` - - `"incomplete"` + Grammar format. Always `grammar`. - - `"failed"` + - `"grammar"` - - `"in_progress"` + - `Namespace object { description, name, tools, type }` - - `type: "computer_call_output"` + Groups function/custom tools under a shared namespace. - The type of the computer tool call output. Always `computer_call_output`. + - `description: string` - - `"computer_call_output"` + 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 }` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + The function/custom tools available inside this namespace. - The safety checks reported by the API that have been acknowledged by the - developer. + - `Function object { name, type, allowed_callers, 5 more }` - - `id: string` + - `name: string` - The ID of the pending safety check. + - `type: "function"` - - `code: optional string` + - `"function"` - 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"` - - `agent: optional object { agent_name }` + - `"programmatic"` - The agent that produced this item. + - `defer_loading: optional boolean` - - `agent_name: string` + Whether this function should be deferred and discovered via tool search. - The canonical name of the agent that produced this item. + - `description: optional string` - - `created_by: optional string` + - `output_schema: optional map[unknown]` - The identifier of the actor that created the item. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `WebSearchCall object { id, action, status, 2 more }` + - `parameters: optional unknown` - The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + - `strict: optional boolean` - - `id: string` + 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 unique ID of the web search tool call. + - `Custom object { name, type, allowed_callers, 3 more }` - - `action: object { type, queries, query, sources } or object { type, url } or 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) - 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). + - `name: string` - - `Search object { type, queries, query, sources }` + The name of the custom tool, used to identify it in tool calls. - Action type "search" - Performs a web search query. + - `type: "custom"` - - `type: "search"` + The type of the custom tool. Always `custom`. - The action type. + - `"custom"` - - `"search"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `queries: optional array of string` + The tool invocation context(s). - The search queries. + - `"direct"` - - `query: optional string` + - `"programmatic"` - The search query. + - `defer_loading: optional boolean` - - `sources: optional array of object { type, url }` + Whether this tool should be deferred and discovered via tool search. - The sources used in the search. + - `description: optional string` - - `type: "url"` + Optional description of the custom tool, used to provide more context. - The type of source. Always `url`. + - `format: optional object { type } or object { definition, syntax, type }` - - `"url"` + The input format for the custom tool. Default is unconstrained text. - - `url: string` + - `Text object { type }` - The URL of the source. + Unconstrained free-form text. - - `OpenPage object { type, url }` + - `type: "text"` - Action type "open_page" - Opens a specific URL from search results. + Unconstrained text format. Always `text`. - - `type: "open_page"` + - `"text"` - The action type. + - `Grammar object { definition, syntax, type }` - - `"open_page"` + A grammar defined by the user. - - `url: optional string` + - `definition: string` - The URL opened by the model. + The grammar definition. - - `FindInPage object { pattern, type, url }` + - `syntax: "lark" or "regex"` - Action type "find_in_page": Searches for a pattern within a loaded page. + The syntax of the grammar definition. One of `lark` or `regex`. - - `pattern: string` + - `"lark"` - The pattern or text to search for within the page. + - `"regex"` - - `type: "find_in_page"` + - `type: "grammar"` - The action type. + Grammar format. Always `grammar`. - - `"find_in_page"` + - `"grammar"` - - `url: string` + - `type: "namespace"` - The URL of the page searched for the pattern. + The type of the tool. Always `namespace`. - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `"namespace"` - The status of the web search tool call. + - `ToolSearch object { type, description, execution, parameters }` - - `"in_progress"` + Hosted or BYOT tool search configuration for deferred tools. - - `"searching"` + - `type: "tool_search"` - - `"completed"` + The type of the tool. Always `tool_search`. - - `"failed"` + - `"tool_search"` - - `type: "web_search_call"` + - `description: optional string` - The type of the web search tool call. Always `web_search_call`. + Description shown to the model for a client-executed tool search tool. - - `"web_search_call"` + - `execution: optional "server" or "client"` - - `agent: optional object { agent_name }` + Whether tool search is executed by the server or by the client. - The agent that produced this item. + - `"server"` - - `agent_name: string` + - `"client"` - The canonical name of the agent that produced this item. + - `parameters: optional unknown` - - `FunctionCall object { id, arguments, call_id, 7 more }` + Parameter schema for a client-executed tool search tool. - - `id: string` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - The unique ID of the function tool call. + 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). - - `arguments: string` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - A JSON string of the arguments to pass to the function. + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `call_id: string` + - `"web_search_preview"` - The unique ID of the function tool call generated by the model. + - `"web_search_preview_2025_03_11"` - - `name: string` + - `search_content_types: optional array of "text" or "image"` - The name of the function to run. + - `"text"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"image"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `search_context_size: optional "low" or "medium" or "high"` - - `"in_progress"` + 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. - - `"completed"` + - `"low"` - - `"incomplete"` + - `"medium"` - - `type: "function_call"` + - `"high"` - The type of the function tool call. Always `function_call`. + - `user_location: optional object { type, city, country, 2 more }` - - `"function_call"` + The user's location. - - `agent: optional object { agent_name }` + - `type: "approximate"` - The agent that produced this item. + The type of location approximation. Always `approximate`. - - `agent_name: string` + - `"approximate"` - The canonical name of the agent that produced this item. + - `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. + - `ApplyPatch object { type, allowed_callers }` - - `type: "program"` + Allows the assistant to create, delete, or update files using unified diffs. - - `"program"` + - `type: "apply_patch"` - - `created_by: optional string` + The type of the tool. Always `apply_patch`. - The identifier of the actor that created the item. + - `"apply_patch"` - - `namespace: optional string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The namespace of the function to run. + The tool invocation context(s). - - `FunctionCallOutput object { id, call_id, output, 5 more }` + - `"direct"` - - `id: string` + - `"programmatic"` - The unique ID of the function call tool output. + - `top_p: number` - - `call_id: string` + 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 unique ID of the function tool call generated by the model. + We generally recommend altering this or `temperature` but not both. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `background: optional boolean` - The output from the function call generated by your code. - Can be a string or an list of output content. + Whether to run the model response in the background. + [Learn more](/docs/guides/background). - - `StringOutput = string` + - `completed_at: optional number` - A string of the output of the function call. + Unix timestamp (in seconds) of when this Response was completed. + Only present when the status is `completed`. - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `conversation: optional object { id }` - Text, image, or file output of the function call. + The conversation that this response belonged to. Input items and output items from this response were automatically added to this conversation. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `id: string` - A text input to the model. + The unique ID of the conversation that this response was associated with. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `max_output_tokens: optional number` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + 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). - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `max_tool_calls: optional number` - A file input to the model. + 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. - - `status: "in_progress" or "completed" or "incomplete"` + - `moderation: optional object { input, output }` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Moderation results for the response input and output, if moderated completions were requested. - - `"in_progress"` + - `input: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - - `"completed"` + Moderation for the response input. - - `"incomplete"` + - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` - - `type: "function_call_output"` + A moderation result produced for the response input or output. - The type of the function tool call output. Always `function_call_output`. + - `categories: map[boolean]` - - `"function_call_output"` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - - `agent: optional object { agent_name }` + - `category_applied_input_types: map[array of "text" or "image"]` - The agent that produced this item. + Which modalities of input are reflected by the score for each category. - - `agent_name: string` + - `"text"` - The canonical name of the agent that produced this item. + - `"image"` - - `caller: optional object { type } or object { caller_id, type }` + - `category_scores: map[number]` - The execution context that produced this tool call. + A dictionary of moderation categories to scores. - - `Direct object { type }` + - `flagged: boolean` - - `type: "direct"` + A boolean indicating whether the content was flagged by any category. - The caller type. Always `direct`. + - `model: string` - - `"direct"` + The moderation model that produced this result. - - `Program object { caller_id, type }` + - `type: "moderation_result"` - - `caller_id: string` + The object type, which was always `moderation_result` for successful moderation results. - The call ID of the program item that produced this tool call. + - `"moderation_result"` - - `type: "program"` + - `Error object { code, message, type }` - The caller type. Always `program`. + An error produced while attempting moderation for the response input or output. - - `"program"` + - `code: string` - - `created_by: optional string` + The error code. - The identifier of the actor that created the item. + - `message: string` - - `AgentMessage object { id, author, content, 3 more }` + The error message. - - `id: string` + - `type: "error"` - The unique ID of the agent message. + The object type, which was always `error` for moderation failures. - - `author: string` + - `"error"` - The sending agent identity. + - `output: object { categories, category_applied_input_types, category_scores, 3 more } or object { code, message, type }` - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + Moderation for the response output. - Encrypted content sent between agents. + - `ModerationResult object { categories, category_applied_input_types, category_scores, 3 more }` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + A moderation result produced for the response input or output. - A text input to the model. + - `categories: map[boolean]` - - `BetaResponseOutputText object { annotations, logprobs, text, type }` + A dictionary of moderation categories to booleans, True if the input is flagged under this category. - A text output from the model. + - `category_applied_input_types: map[array of "text" or "image"]` - - `Text object { text, type }` + Which modalities of input are reflected by the score for each category. - A text content. + - `"text"` - - `text: string` + - `"image"` - - `type: "text"` + - `category_scores: map[number]` - - `"text"` + A dictionary of moderation categories to scores. - - `SummaryText object { text, type }` + - `flagged: boolean` - A summary text from the model. + A boolean indicating whether the content was flagged by any category. - - `text: string` + - `model: string` - A summary of the reasoning output from the model so far. + The moderation model that produced this result. - - `type: "summary_text"` + - `type: "moderation_result"` - The type of the object. Always `summary_text`. + The object type, which was always `moderation_result` for successful moderation results. - - `"summary_text"` + - `"moderation_result"` - - `ReasoningText object { text, type }` + - `Error object { code, message, type }` - Reasoning text from the model. + An error produced while attempting moderation for the response input or output. - - `text: string` + - `code: string` - The reasoning text from the model. + The error code. - - `type: "reasoning_text"` + - `message: string` - The type of the reasoning text. Always `reasoning_text`. + The error message. - - `"reasoning_text"` + - `type: "error"` - - `BetaResponseOutputRefusal object { refusal, type }` + The object type, which was always `error` for moderation failures. - A refusal from the model. + - `"error"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `output_text: optional string` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + 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. - - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` + - `previous_response_id: optional string` - A screenshot of a computer. + 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`. - - `detail: "low" or "high" or "auto" or "original"` + - `prompt: optional BetaResponsePrompt` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Reference to a prompt template and its variables. + [Learn more](/docs/guides/text?api-mode=responses#reusable-prompts). - - `"low"` + - `id: string` - - `"high"` + The unique identifier of the prompt template to use. - - `"auto"` + - `variables: optional map[string or BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile]` - - `"original"` + 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. - - `file_id: string` + - `string` - The identifier of an uploaded file that contains the screenshot. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `image_url: string` + A text input to the model. - The URL of the screenshot image. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `type: "computer_screenshot"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `"computer_screenshot"` + A file input to the model. - - `prompt_cache_breakpoint: optional object { mode }` + - `version: 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. + Optional version of the prompt template. - - `mode: "explicit"` + - `prompt_cache_key: optional string` - The breakpoint mode. Always `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). - - `"explicit"` + - `prompt_cache_options: optional object { mode, ttl }` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + The prompt-caching options that were applied to the response. Supported for `gpt-5.6` and later models. - A file input to the model. + - `mode: "implicit" or "explicit"` - - `EncryptedContent object { encrypted_content, type }` + Whether implicit prompt-cache breakpoints were enabled. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `"implicit"` - - `encrypted_content: string` + - `"explicit"` - Opaque encrypted content. + - `ttl: "30m"` - - `type: "encrypted_content"` + The minimum lifetime applied to each cache breakpoint. - The type of the input item. Always `encrypted_content`. + - `"30m"` - - `"encrypted_content"` + - `prompt_cache_retention: optional "in_memory" or "24h"` - - `recipient: string` + Deprecated. Use `prompt_cache_options.ttl` instead. - The destination agent identity. + 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. - - `type: "agent_message"` + For older models that support both `in_memory` and `24h`, the default depends on your organization's data retention policy: - The type of the item. Always `agent_message`. + - Organizations without ZDR enabled default to `24h`. + - Organizations with ZDR enabled default to `in_memory` when `prompt_cache_retention` is not specified. - - `"agent_message"` + - `"in_memory"` - - `agent: optional object { agent_name }` + - `"24h"` - The agent that produced this item. + - `reasoning: optional object { context, effort, generate_summary, 2 more }` - - `agent_name: string` + **gpt-5 and o-series models only** - The canonical name of the agent that produced this item. + Configuration options for + [reasoning models](https://platform.openai.com/docs/guides/reasoning). - - `MultiAgentCall object { id, action, arguments, 3 more }` + - `context: optional "auto" or "current_turn" or "all_turns"` - - `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`. - The unique ID of the multi-agent call item. + When returned on a response, this is the effective reasoning context mode + used for the response. - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `"auto"` - The multi-agent action to execute. + - `"current_turn"` - - `"spawn_agent"` + - `"all_turns"` - - `"interrupt_agent"` + - `effort: optional "none" or "minimal" or "low" or 4 more` - - `"list_agents"` + 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. - - `"send_message"` + - `"none"` - - `"followup_task"` + - `"minimal"` - - `"wait_agent"` + - `"low"` - - `arguments: string` + - `"medium"` - The JSON string of arguments generated for the action. + - `"high"` - - `call_id: string` + - `"xhigh"` - The unique ID linking this call to its output. + - `"max"` - - `type: "multi_agent_call"` + - `generate_summary: optional "auto" or "concise" or "detailed"` - The type of the multi-agent call. Always `multi_agent_call`. + **Deprecated:** use `summary` instead. - - `"multi_agent_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`. - - `agent: optional object { agent_name }` + - `"auto"` - The agent that produced this item. + - `"concise"` - - `agent_name: string` + - `"detailed"` - The canonical name of the agent that produced this item. + - `mode: optional string or "standard" or "pro"` - - `MultiAgentCallOutput object { id, action, call_id, 3 more }` + Controls the reasoning execution mode for the request. - - `id: string` + When returned on a response, this is the effective execution mode. - The unique ID of the multi-agent call output item. + - `string` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `"standard" or "pro"` - The multi-agent action that produced this result. + Controls the reasoning execution mode for the request. - - `"spawn_agent"` + When returned on a response, this is the effective execution mode. - - `"interrupt_agent"` + - `"standard"` - - `"list_agents"` + - `"pro"` - - `"send_message"` + - `summary: optional "auto" or "concise" or "detailed"` - - `"followup_task"` + 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`. - - `"wait_agent"` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `call_id: string` + - `"auto"` - The unique ID of the multi-agent call. + - `"concise"` - - `output: array of BetaResponseOutputText` + - `"detailed"` - Text output returned by the multi-agent action. + - `safety_identifier: optional string` - - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` + 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 annotations of the text output. + - `service_tier: optional "auto" or "default" or "flex" or 2 more` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + Specifies the processing type used for serving the request. - - `text: string` + - 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 text output from the model. + 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: "output_text"` + - `"auto"` - The type of the output text. Always `output_text`. + - `"default"` - - `type: "multi_agent_call_output"` + - `"flex"` - The type of the multi-agent result. Always `multi_agent_call_output`. + - `"scale"` - - `"multi_agent_call_output"` + - `"priority"` - - `agent: optional object { agent_name }` + - `status: optional BetaResponseStatus` - The agent that produced this item. + The status of the response generation. One of `completed`, `failed`, + `in_progress`, `cancelled`, `queued`, or `incomplete`. - - `agent_name: string` + - `"completed"` - The canonical name of the agent that produced this item. + - `"failed"` - - `ToolSearchCall object { id, arguments, call_id, 5 more }` + - `"in_progress"` - - `id: string` + - `"cancelled"` - The unique ID of the tool search call item. + - `"queued"` - - `arguments: unknown` + - `"incomplete"` - Arguments used for the tool search call. + - `text: optional BetaResponseTextConfig` - - `call_id: string` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - The unique ID of the tool search call generated by the model. + - [Text inputs and outputs](/docs/guides/text) + - [Structured Outputs](/docs/guides/structured-outputs) - - `execution: "server" or "client"` + - `format: optional BetaResponseFormatTextConfig` - Whether tool search was executed by the server or by the client. + An object specifying the format that the model must output. - - `"server"` + 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). - - `"client"` + The default format is `{ "type": "text" }` with no additional options. - - `status: "in_progress" or "completed" or "incomplete"` + **Not recommended for gpt-4o and newer models:** - The status of the tool search call item that was recorded. + 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. - - `"in_progress"` + - `Text object { type }` - - `"completed"` + Default response format. Used to generate text responses. - - `"incomplete"` + - `type: "text"` - - `type: "tool_search_call"` + The type of response format being defined. Always `text`. - The type of the item. Always `tool_search_call`. + - `"text"` - - `"tool_search_call"` + - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` - - `agent: optional object { agent_name }` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - The agent that produced this item. + - `name: string` - - `agent_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. - The canonical name of the agent that produced this item. + - `schema: map[unknown]` - - `created_by: optional string` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - The identifier of the actor that created the item. + - `type: "json_schema"` - - `ToolSearchOutput object { id, call_id, execution, 5 more }` + The type of response format being defined. Always `json_schema`. - - `id: string` + - `"json_schema"` - The unique ID of the tool search output item. + - `description: optional string` - - `call_id: string` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The unique ID of the tool search call generated by the model. + - `strict: optional boolean` - - `execution: "server" or "client"` + 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). - Whether tool search was executed by the server or by the client. + - `JSONObject object { type }` - - `"server"` + 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. - - `"client"` + - `type: "json_object"` - - `status: "in_progress" or "completed" or "incomplete"` + The type of response format being defined. Always `json_object`. - The status of the tool search output item that was recorded. + - `"json_object"` - - `"in_progress"` + - `verbosity: optional "low" or "medium" or "high"` - - `"completed"` + 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`. - - `"incomplete"` + - `"low"` - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + - `"medium"` - The loaded tool definitions returned by tool search. + - `"high"` - - `Function object { name, parameters, strict, 5 more }` + - `top_logprobs: optional number` - 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). + 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. - - `name: string` + - `truncation: optional "auto" or "disabled"` - The name of the function to call. + The truncation strategy to use for the model response. - - `parameters: map[unknown]` + - `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. - A JSON schema object describing the parameters of the function. + - `"auto"` - - `strict: boolean` + - `"disabled"` - Whether strict parameter validation is enforced for this function tool. + - `usage: optional BetaResponseUsage` - - `type: "function"` + Represents token usage details including input tokens, output tokens, + a breakdown of output tokens, and the total tokens used. - The type of the function tool. Always `function`. + - `input_tokens: number` - - `"function"` + The number of input tokens. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `input_tokens_details: object { cache_write_tokens, cached_tokens }` - The tool invocation context(s). + A detailed breakdown of the input tokens. - - `"direct"` + - `cache_write_tokens: number` - - `"programmatic"` + The number of input tokens that were written to the cache. - - `defer_loading: optional boolean` + - `cached_tokens: number` - Whether this function is deferred and loaded via tool search. + The number of tokens that were retrieved from the cache. + [More on prompt caching](/docs/guides/prompt-caching). - - `description: optional string` + - `output_tokens: number` - A description of the function. Used by the model to determine whether or not to call the function. + The number of output tokens. - - `output_schema: optional map[unknown]` + - `output_tokens_details: object { reasoning_tokens }` - A JSON schema object describing the JSON value encoded in string outputs for this function. + A detailed breakdown of the output tokens. - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `reasoning_tokens: number` - 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 number of reasoning tokens. - - `type: "file_search"` + - `total_tokens: number` - The type of the file search tool. Always `file_search`. + The total number of tokens used. - - `"file_search"` + - `user: optional string` - - `vector_store_ids: 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). - The IDs of the vector stores to search. + - `sequence_number: number` - - `filters: optional object { key, type, value } or object { filters, type }` + The sequence number for this event. - A filter to apply. + - `type: "response.completed"` - - `ComparisonFilter object { key, type, value }` + The type of the event. Always `response.completed`. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `"response.completed"` - - `key: string` + - `agent: optional object { agent_name }` - The key to compare against the value. + The agent that owns this multi-agent streaming event. - - `type: "eq" or "ne" or "gt" or 5 more` + - `agent_name: string` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The canonical name of the agent that produced this item. - - `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 + - `BetaResponseContentPartAddedEvent object { content_index, item_id, output_index, 4 more }` - - `"eq"` + Emitted when a new content part is added. - - `"ne"` + - `content_index: number` - - `"gt"` + The index of the content part that was added. - - `"gte"` + - `item_id: string` - - `"lt"` + The ID of the output item that the content part was added to. - - `"lte"` + - `output_index: number` - - `"in"` + The index of the output item that the content part was added to. - - `"nin"` + - `part: BetaResponseOutputText or BetaResponseOutputRefusal or object { text, type }` - - `value: string or number or boolean or array of string or number` + The content part that was added. - The value to compare against the attribute key; supports string, number, or boolean types. + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - - `string` + A text output from the model. - - `number` + - `BetaResponseOutputRefusal object { refusal, type }` - - `boolean` + A refusal from the model. - - `array of string or number` + - `ReasoningText object { text, type }` - - `string` + Reasoning text from the model. - - `number` + - `text: string` - - `CompoundFilter object { filters, type }` + The reasoning text from the model. - Combine multiple filters using `and` or `or`. + - `type: "reasoning_text"` - - `filters: array of object { key, type, value } or unknown` + The type of the reasoning text. Always `reasoning_text`. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `"reasoning_text"` - - `ComparisonFilter object { key, type, value }` + - `sequence_number: number` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + The sequence number of this event. - - `key: string` + - `type: "response.content_part.added"` - The key to compare against the value. + The type of the event. Always `response.content_part.added`. - - `type: "eq" or "ne" or "gt" or 5 more` + - `"response.content_part.added"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `agent: optional object { agent_name }` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + The agent that owns this multi-agent streaming event. - - `"eq"` + - `agent_name: string` - - `"ne"` + The canonical name of the agent that produced this item. - - `"gt"` + - `BetaResponseContentPartDoneEvent object { content_index, item_id, output_index, 4 more }` - - `"gte"` + Emitted when a content part is done. - - `"lt"` + - `content_index: number` - - `"lte"` + The index of the content part that is done. - - `"in"` + - `item_id: string` - - `"nin"` + The ID of the output item that the content part was added to. - - `value: string or number or boolean or array of string or number` + - `output_index: number` - The value to compare against the attribute key; supports string, number, or boolean types. + The index of the output item that the content part was added to. - - `string` + - `part: BetaResponseOutputText or BetaResponseOutputRefusal or object { text, type }` - - `number` + The content part that is done. - - `boolean` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - - `array of string or number` + A text output from the model. - - `string` + - `BetaResponseOutputRefusal object { refusal, type }` - - `number` + A refusal from the model. - - `unknown` + - `ReasoningText object { text, type }` - - `type: "and" or "or"` + Reasoning text from the model. - Type of operation: `and` or `or`. + - `text: string` - - `"and"` + The reasoning text from the model. - - `"or"` + - `type: "reasoning_text"` - - `max_num_results: optional number` + The type of the reasoning text. Always `reasoning_text`. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `"reasoning_text"` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `sequence_number: number` - Ranking options for search. + The sequence number of this event. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `type: "response.content_part.done"` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + The type of the event. Always `response.content_part.done`. - - `embedding_weight: number` + - `"response.content_part.done"` - The weight of the embedding in the reciprocal ranking fusion. + - `agent: optional object { agent_name }` - - `text_weight: number` + The agent that owns this multi-agent streaming event. - The weight of the text in the reciprocal ranking fusion. + - `agent_name: string` - - `ranker: optional "auto" or "default-2024-11-15"` + The canonical name of the agent that produced this item. - The ranker to use for the file search. + - `BetaResponseCreatedEvent object { response, sequence_number, type, agent }` - - `"auto"` + An event that is emitted when a response is created. - - `"default-2024-11-15"` + - `response: BetaResponse` - - `score_threshold: optional number` + The response that was created. - 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. + - `sequence_number: number` - - `Computer object { type }` + The sequence number for this event. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `type: "response.created"` - - `type: "computer"` + The type of the event. Always `response.created`. - The type of the computer tool. Always `computer`. + - `"response.created"` - - `"computer"` + - `agent: optional object { agent_name }` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + The agent that owns this multi-agent streaming event. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `agent_name: string` - - `display_height: number` + The canonical name of the agent that produced this item. - The height of the computer display. + - `BetaResponseErrorEvent object { code, message, param, 3 more }` - - `display_width: number` + Emitted when an error occurs. - The width of the computer display. + - `code: string` - - `environment: "windows" or "mac" or "linux" or 2 more` + The error code. - The type of computer environment to control. + - `message: string` - - `"windows"` + The error message. - - `"mac"` + - `param: string` - - `"linux"` + The error parameter. - - `"ubuntu"` + - `sequence_number: number` - - `"browser"` + The sequence number of this event. - - `type: "computer_use_preview"` + - `type: "error"` - The type of the computer use tool. Always `computer_use_preview`. + The type of the event. Always `error`. - - `"computer_use_preview"` + - `"error"` - - `WebSearch object { type, filters, search_context_size, user_location }` + - `agent: optional object { agent_name }` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + The agent that owns this multi-agent streaming event. - - `type: "web_search" or "web_search_2025_08_26"` + - `agent_name: string` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + The canonical name of the agent that produced this item. - - `"web_search"` + - `BetaResponseFileSearchCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - - `"web_search_2025_08_26"` + Emitted when a file search call is completed (results found). - - `filters: optional object { allowed_domains }` + - `item_id: string` - Filters for the search. + The ID of the output item that the file search call is initiated. - - `allowed_domains: optional array of string` + - `output_index: number` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + The index of the output item that the file search call is initiated. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `sequence_number: number` - - `search_context_size: optional "low" or "medium" or "high"` + The sequence number of this event. - 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: "response.file_search_call.completed"` - - `"low"` + The type of the event. Always `response.file_search_call.completed`. - - `"medium"` + - `"response.file_search_call.completed"` - - `"high"` + - `agent: optional object { agent_name }` - - `user_location: optional object { city, country, region, 2 more }` + The agent that owns this multi-agent streaming event. - The approximate location of the user. + - `agent_name: string` - - `city: optional string` + The canonical name of the agent that produced this item. - Free text input for the city of the user, e.g. `San Francisco`. + - `BetaResponseFileSearchCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` - - `country: optional string` + Emitted when a file search call is initiated. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `item_id: string` - - `region: optional string` + The ID of the output item that the file search call is initiated. - Free text input for the region of the user, e.g. `California`. + - `output_index: number` - - `timezone: optional string` + The index of the output item that the file search call is initiated. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `sequence_number: number` - - `type: optional "approximate"` + The sequence number of this event. - The type of location approximation. Always `approximate`. + - `type: "response.file_search_call.in_progress"` - - `"approximate"` + The type of the event. Always `response.file_search_call.in_progress`. - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `"response.file_search_call.in_progress"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + - `agent: optional object { agent_name }` - - `server_label: string` + The agent that owns this multi-agent streaming event. - A label for this MCP server, used to identify it in tool calls. + - `agent_name: string` - - `type: "mcp"` + The canonical name of the agent that produced this item. - The type of the MCP tool. Always `mcp`. + - `BetaResponseFileSearchCallSearchingEvent object { item_id, output_index, sequence_number, 2 more }` - - `"mcp"` + Emitted when a file search is currently searching. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `item_id: string` - The tool invocation context(s). + The ID of the output item that the file search call is initiated. - - `"direct"` + - `output_index: number` - - `"programmatic"` + The index of the output item that the file search call is searching. - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `sequence_number: number` - List of allowed tool names or a filter object. + The sequence number of this event. - - `McpAllowedTools = array of string` + - `type: "response.file_search_call.searching"` - A string array of allowed tool names + The type of the event. Always `response.file_search_call.searching`. - - `McpToolFilter object { read_only, tool_names }` + - `"response.file_search_call.searching"` - A filter object to specify which tools are allowed. + - `agent: optional object { agent_name }` - - `read_only: optional boolean` + The agent that owns this multi-agent streaming event. - 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. + - `agent_name: string` - - `tool_names: optional array of string` + The canonical name of the agent that produced this item. - List of allowed tool names. + - `BetaResponseFunctionCallArgumentsDeltaEvent object { delta, item_id, output_index, 3 more }` - - `authorization: optional string` + Emitted when there is a partial function-call arguments delta. - 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. + - `delta: string` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + The function-call arguments delta that is added. - 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). + - `item_id: string` - Currently supported `connector_id` values are: + The ID of the output item that the function-call arguments delta is added to. - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `output_index: number` - - `"connector_dropbox"` + The index of the output item that the function-call arguments delta is added to. - - `"connector_gmail"` + - `sequence_number: number` - - `"connector_googlecalendar"` + The sequence number of this event. - - `"connector_googledrive"` + - `type: "response.function_call_arguments.delta"` - - `"connector_microsoftteams"` + The type of the event. Always `response.function_call_arguments.delta`. - - `"connector_outlookcalendar"` + - `"response.function_call_arguments.delta"` - - `"connector_outlookemail"` + - `agent: optional object { agent_name }` - - `"connector_sharepoint"` + The agent that owns this multi-agent streaming event. - - `defer_loading: optional boolean` + - `agent_name: string` - Whether this MCP tool is deferred and discovered via tool search. + The canonical name of the agent that produced this item. - - `headers: optional map[string]` + - `BetaResponseFunctionCallArgumentsDoneEvent object { arguments, item_id, name, 4 more }` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + Emitted when function-call arguments are finalized. - - `require_approval: optional object { always, never } or "always" or "never"` + - `arguments: string` - Specify which of the MCP server's tools require approval. + The function-call arguments. - - `McpToolApprovalFilter object { always, never }` + - `item_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 item. - - `always: optional object { read_only, tool_names }` + - `name: string` - A filter object to specify which tools are allowed. + The name of the function that was called. - - `read_only: optional boolean` + - `output_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 output item. - - `tool_names: optional array of string` + - `sequence_number: number` - List of allowed tool names. + The sequence number of this event. - - `never: optional object { read_only, tool_names }` + - `type: "response.function_call_arguments.done"` - A filter object to specify which tools are allowed. + - `"response.function_call_arguments.done"` - - `read_only: optional boolean` + - `agent: optional object { agent_name }` - 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 agent that owns this multi-agent streaming event. - - `tool_names: optional array of string` + - `agent_name: string` - List of allowed tool names. + The canonical name of the agent that produced this item. - - `McpToolApprovalSetting = "always" or "never"` + - `BetaResponseInProgressEvent object { response, sequence_number, type, agent }` - 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. + Emitted when the response is in progress. - - `"always"` + - `response: BetaResponse` - - `"never"` + The response that is in progress. - - `server_description: optional string` + - `sequence_number: number` - Optional description of the MCP server, used to provide more context. + The sequence number of this event. - - `server_url: optional string` + - `type: "response.in_progress"` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + The type of the event. Always `response.in_progress`. - - `tunnel_id: optional string` + - `"response.in_progress"` - 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. + - `agent: optional object { agent_name }` - - `CodeInterpreter object { container, type, allowed_callers }` + The agent that owns this multi-agent streaming event. - A tool that runs Python code to help generate a response to a prompt. + - `agent_name: string` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + The canonical name of the agent that produced this item. - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + - `BetaResponseFailedEvent object { response, sequence_number, type, agent }` - - `string` + An event that is emitted when a response fails. - The container ID. + - `response: BetaResponse` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + The response that failed. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `sequence_number: number` - - `type: "auto"` + The sequence number of this event. - Always `auto`. + - `type: "response.failed"` - - `"auto"` + The type of the event. Always `response.failed`. - - `file_ids: optional array of string` + - `"response.failed"` - An optional list of uploaded files to make available to your code. + - `agent: optional object { agent_name }` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + The agent that owns this multi-agent streaming event. - The memory limit for the code interpreter container. + - `agent_name: string` - - `"1g"` + The canonical name of the agent that produced this item. - - `"4g"` + - `BetaResponseIncompleteEvent object { response, sequence_number, type, agent }` - - `"16g"` + An event that is emitted when a response finishes as incomplete. - - `"64g"` + - `response: BetaResponse` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + The response that was incomplete. - Network access policy for the container. + - `sequence_number: number` - - `BetaContainerNetworkPolicyDisabled object { type }` + The sequence number of this event. - - `type: "disabled"` + - `type: "response.incomplete"` - Disable outbound network access. Always `disabled`. + The type of the event. Always `response.incomplete`. - - `"disabled"` + - `"response.incomplete"` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `agent: optional object { agent_name }` - - `allowed_domains: array of string` + The agent that owns this multi-agent streaming event. - A list of allowed domains when type is `allowlist`. + - `agent_name: string` - - `type: "allowlist"` + The canonical name of the agent that produced this item. - Allow outbound network access only to specified domains. Always `allowlist`. + - `BetaResponseOutputItemAddedEvent object { item, output_index, sequence_number, 2 more }` - - `"allowlist"` + Emitted when a new output item is added. - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + - `item: BetaResponseOutputItem` - Optional domain-scoped secrets for allowlisted domains. + The output item that was added. - - `domain: string` + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - The domain associated with the secret. + An output message from the model. - - `name: string` + - `FileSearchCall object { id, queries, status, 3 more }` - The name of the secret to inject for the domain. + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - - `value: string` + - `FunctionCall object { arguments, call_id, name, 6 more }` - The secret value to inject for the domain. + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - - `type: "code_interpreter"` + - `FunctionCallOutput object { id, call_id, output, 5 more }` - The type of the code interpreter tool. Always `code_interpreter`. + - `AgentMessage object { id, author, content, 3 more }` - - `"code_interpreter"` + - `MultiAgentCall object { id, action, arguments, 3 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `MultiAgentCallOutput object { id, action, call_id, 3 more }` - The tool invocation context(s). + - `WebSearchCall object { id, action, status, 2 more }` - - `"direct"` + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `"programmatic"` + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - - `ProgrammaticToolCalling object { type }` + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - - `type: "programmatic_tool_calling"` + - `ComputerCallOutput object { id, call_id, output, 5 more }` - The type of the tool. Always `programmatic_tool_calling`. + - `Reasoning object { id, summary, type, 4 more }` - - `"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). - - `ImageGeneration object { type, action, background, 9 more }` + - `Program object { id, call_id, code, 3 more }` - A tool that generates images using the GPT image models. + - `ProgramOutput object { id, call_id, result, 3 more }` - - `type: "image_generation"` + - `ToolSearchCall object { id, arguments, call_id, 5 more }` - The type of the image generation tool. Always `image_generation`. + - `ToolSearchOutput object { id, call_id, execution, 5 more }` - - `"image_generation"` + - `AdditionalTools object { id, role, tools, 2 more }` - - `action: optional "generate" or "edit" or "auto"` + - `Compaction object { id, encrypted_content, type, 2 more }` - Whether to generate a new image or edit an existing image. Default: `auto`. + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - - `"generate"` + - `ImageGenerationCall object { id, result, status, 2 more }` - - `"edit"` + An image generation request made by the model. - - `"auto"` + - `CodeInterpreterCall object { id, code, container_id, 4 more }` - - `background: optional "transparent" or "opaque" or "auto"` + A tool call to run code. - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + - `LocalShellCall object { id, action, call_id, 3 more }` - - `"transparent"` + A tool call to run a command on the local shell. - - `"opaque"` + - `LocalShellCallOutput object { id, output, type, 2 more }` - - `"auto"` + The output of a local shell tool call. - - `input_fidelity: optional "high" or "low"` + - `ShellCall object { id, action, call_id, 6 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 executes one or more shell commands in a managed environment. - - `"high"` + - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` - - `"low"` + The output of a shell tool call that was emitted. - - `input_image_mask: optional object { file_id, image_url }` + - `ApplyPatchCall object { id, call_id, operation, 5 more }` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + A tool call that applies file diffs by creating, deleting, or updating files. - - `file_id: optional string` + - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` - File ID for the mask image. + The output emitted by an apply patch tool call. - - `image_url: optional string` + - `McpCall object { id, arguments, name, 7 more }` - Base64-encoded mask image. + An invocation of a tool on an MCP server. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `McpListTools object { id, server_label, tools, 3 more }` - The image generation model to use. Default: `gpt-image-1`. + A list of tools available on an MCP server. - - `string` + - `McpApprovalRequest object { id, arguments, name, 3 more }` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + A request for human approval of a tool invocation. - The image generation model to use. Default: `gpt-image-1`. + - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` - - `"gpt-image-1"` + A response to an MCP approval request. - - `"gpt-image-1-mini"` + - `CustomToolCall object { call_id, input, name, 5 more }` - - `"gpt-image-1.5"` + A call to a custom tool created by the model. - - `moderation: optional "auto" or "low"` + - `CustomToolCallOutput object { id, call_id, output, 5 more }` - Moderation level for the generated image. Default: `auto`. + - `output_index: number` - - `"auto"` + The index of the output item that was added. - - `"low"` + - `sequence_number: number` - - `output_compression: optional number` + The sequence number of this event. - Compression level for the output image. Default: 100. + - `type: "response.output_item.added"` - - `output_format: optional "png" or "webp" or "jpeg"` + The type of the event. Always `response.output_item.added`. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `"response.output_item.added"` - - `"png"` + - `agent: optional object { agent_name }` - - `"webp"` + The agent that owns this multi-agent streaming event. - - `"jpeg"` + - `agent_name: string` - - `partial_images: optional number` + The canonical name of the agent that produced this item. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `BetaResponseOutputItemDoneEvent object { item, output_index, sequence_number, 2 more }` - - `quality: optional "low" or "medium" or "high" or "auto"` + Emitted when an output item is marked done. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `item: BetaResponseOutputItem` - - `"low"` + The output item that was marked done. - - `"medium"` + - `output_index: number` - - `"high"` + The index of the output item that was marked done. - - `"auto"` + - `sequence_number: number` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The sequence number of this event. - 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: "response.output_item.done"` - - `string` + The type of the event. Always `response.output_item.done`. - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `"response.output_item.done"` - 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`. + - `agent: optional object { agent_name }` - - `"1024x1024"` + The agent that owns this multi-agent streaming event. - - `"1024x1536"` + - `agent_name: string` - - `"1536x1024"` + The canonical name of the agent that produced this item. - - `"auto"` + - `BetaResponseReasoningSummaryPartAddedEvent object { item_id, output_index, part, 4 more }` - - `LocalShell object { type }` + Emitted when a new reasoning summary part is added. - A tool that allows the model to execute shell commands in a local environment. + - `item_id: string` - - `type: "local_shell"` + The ID of the item this summary part is associated with. - The type of the local shell tool. Always `local_shell`. + - `output_index: number` - - `"local_shell"` + The index of the output item this summary part is associated with. - - `Shell object { type, allowed_callers, environment }` + - `part: object { text, type }` - A tool that allows the model to execute shell commands. + The summary part that was added. - - `type: "shell"` + - `text: string` - The type of the shell tool. Always `shell`. + The text of the summary part. - - `"shell"` + - `type: "summary_text"` - - `allowed_callers: optional array of "direct" or "programmatic"` + The type of the summary part. Always `summary_text`. - The tool invocation context(s). + - `"summary_text"` - - `"direct"` + - `sequence_number: number` - - `"programmatic"` + The sequence number of this event. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `summary_index: number` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + The index of the summary part within the reasoning summary. - - `type: "container_auto"` + - `type: "response.reasoning_summary_part.added"` - Automatically creates a container for this request + The type of the event. Always `response.reasoning_summary_part.added`. - - `"container_auto"` + - `"response.reasoning_summary_part.added"` - - `file_ids: optional array of string` + - `agent: optional object { agent_name }` - An optional list of uploaded files to make available to your code. + The agent that owns this multi-agent streaming event. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `agent_name: string` - The memory limit for the container. + The canonical name of the agent that produced this item. - - `"1g"` + - `BetaResponseReasoningSummaryPartDoneEvent object { item_id, output_index, part, 5 more }` - - `"4g"` + Emitted when a reasoning summary part is completed. - - `"16g"` + - `item_id: string` - - `"64g"` + The ID of the item this summary part is associated with. - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `output_index: number` - Network access policy for the container. + The index of the output item this summary part is associated with. - - `BetaContainerNetworkPolicyDisabled object { type }` + - `part: object { text, type }` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + The completed summary part. - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + - `text: string` - An optional list of skills referenced by id or inline data. + The text of the summary part. - - `BetaSkillReference object { skill_id, type, version }` + - `type: "summary_text"` - - `skill_id: string` + The type of the summary part. Always `summary_text`. - The ID of the referenced skill. + - `"summary_text"` - - `type: "skill_reference"` + - `sequence_number: number` - References a skill created with the /v1/skills endpoint. + The sequence number of this event. - - `"skill_reference"` + - `summary_index: number` - - `version: optional string` + The index of the summary part within the reasoning summary. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `type: "response.reasoning_summary_part.done"` - - `BetaInlineSkill object { description, name, source, type }` + The type of the event. Always `response.reasoning_summary_part.done`. - - `description: string` + - `"response.reasoning_summary_part.done"` - The description of the skill. + - `agent: optional object { agent_name }` - - `name: string` + The agent that owns this multi-agent streaming event. - The name of the skill. + - `agent_name: string` - - `source: BetaInlineSkillSource` + The canonical name of the agent that produced this item. - Inline skill payload + - `status: optional "incomplete"` - - `data: string` + The completion status of the summary part. Omitted when the part completed + normally and set to `incomplete` when generation was interrupted. - Base64-encoded skill zip bundle. + - `"incomplete"` - - `media_type: "application/zip"` + - `BetaResponseReasoningSummaryTextDeltaEvent object { delta, item_id, output_index, 4 more }` - The media type of the inline skill payload. Must be `application/zip`. + Emitted when a delta is added to a reasoning summary text. - - `"application/zip"` + - `delta: string` - - `type: "base64"` + The text delta that was added to the summary. - The type of the inline skill source. Must be `base64`. + - `item_id: string` - - `"base64"` + The ID of the item this summary text delta is associated with. - - `type: "inline"` + - `output_index: number` - Defines an inline skill for this request. + The index of the output item this summary text delta is associated with. - - `"inline"` + - `sequence_number: number` - - `BetaLocalEnvironment object { type, skills }` + The sequence number of this event. - - `type: "local"` + - `summary_index: number` - Use a local computer environment. + The index of the summary part within the reasoning summary. - - `"local"` + - `type: "response.reasoning_summary_text.delta"` - - `skills: optional array of BetaLocalSkill` + The type of the event. Always `response.reasoning_summary_text.delta`. - An optional list of skills. + - `"response.reasoning_summary_text.delta"` - - `description: string` + - `agent: optional object { agent_name }` - The description of the skill. + The agent that owns this multi-agent streaming event. - - `name: string` + - `agent_name: string` - The name of the skill. + The canonical name of the agent that produced this item. - - `path: string` + - `BetaResponseReasoningSummaryTextDoneEvent object { item_id, output_index, sequence_number, 4 more }` - The path to the directory containing the skill. + Emitted when a reasoning summary text is completed. - - `BetaContainerReference object { container_id, type }` + - `item_id: string` - - `container_id: string` + The ID of the item this summary text is associated with. - The ID of the referenced container. + - `output_index: number` - - `type: "container_reference"` + The index of the output item this summary text is associated with. - References a container created with the /v1/containers endpoint + - `sequence_number: number` - - `"container_reference"` + The sequence number of this event. - - `Custom object { name, type, allowed_callers, 3 more }` + - `summary_index: number` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + The index of the summary part within the reasoning summary. - - `name: string` + - `text: string` - The name of the custom tool, used to identify it in tool calls. + The full text of the completed reasoning summary. - - `type: "custom"` + - `type: "response.reasoning_summary_text.done"` - The type of the custom tool. Always `custom`. + The type of the event. Always `response.reasoning_summary_text.done`. - - `"custom"` + - `"response.reasoning_summary_text.done"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `agent: optional object { agent_name }` - The tool invocation context(s). + The agent that owns this multi-agent streaming event. - - `"direct"` + - `agent_name: string` - - `"programmatic"` + The canonical name of the agent that produced this item. - - `defer_loading: optional boolean` + - `BetaResponseReasoningTextDeltaEvent object { content_index, delta, item_id, 4 more }` - Whether this tool should be deferred and discovered via tool search. + Emitted when a delta is added to a reasoning text. - - `description: optional string` + - `content_index: number` - Optional description of the custom tool, used to provide more context. + The index of the reasoning content part this delta is associated with. - - `format: optional object { type } or object { definition, syntax, type }` + - `delta: string` - The input format for the custom tool. Default is unconstrained text. + The text delta that was added to the reasoning content. - - `Text object { type }` + - `item_id: string` - Unconstrained free-form text. + The ID of the item this reasoning text delta is associated with. - - `type: "text"` + - `output_index: number` - Unconstrained text format. Always `text`. + The index of the output item this reasoning text delta is associated with. - - `"text"` + - `sequence_number: number` - - `Grammar object { definition, syntax, type }` + The sequence number of this event. - A grammar defined by the user. + - `type: "response.reasoning_text.delta"` - - `definition: string` + The type of the event. Always `response.reasoning_text.delta`. - The grammar definition. + - `"response.reasoning_text.delta"` - - `syntax: "lark" or "regex"` + - `agent: optional object { agent_name }` - The syntax of the grammar definition. One of `lark` or `regex`. + The agent that owns this multi-agent streaming event. - - `"lark"` + - `agent_name: string` - - `"regex"` + The canonical name of the agent that produced this item. - - `type: "grammar"` + - `BetaResponseReasoningTextDoneEvent object { content_index, item_id, output_index, 4 more }` - Grammar format. Always `grammar`. + Emitted when a reasoning text is completed. - - `"grammar"` + - `content_index: number` - - `Namespace object { description, name, tools, type }` + The index of the reasoning content part. - Groups function/custom tools under a shared namespace. + - `item_id: string` - - `description: string` + The ID of the item this reasoning text is associated with. - A description of the namespace shown to the model. + - `output_index: number` - - `name: string` + The index of the output item this reasoning text is associated with. - The namespace name used in tool calls (for example, `crm`). + - `sequence_number: number` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + The sequence number of this event. - The function/custom tools available inside this namespace. + - `text: string` - - `Function object { name, type, allowed_callers, 5 more }` + The full text of the completed reasoning content. - - `name: string` + - `type: "response.reasoning_text.done"` - - `type: "function"` + The type of the event. Always `response.reasoning_text.done`. - - `"function"` + - `"response.reasoning_text.done"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `agent: optional object { agent_name }` - The tool invocation context(s). + The agent that owns this multi-agent streaming event. - - `"direct"` + - `agent_name: string` - - `"programmatic"` + The canonical name of the agent that produced this item. - - `defer_loading: optional boolean` + - `BetaResponseRefusalDeltaEvent object { content_index, delta, item_id, 4 more }` - Whether this function should be deferred and discovered via tool search. + Emitted when there is a partial refusal text. - - `description: optional string` + - `content_index: number` - - `output_schema: optional map[unknown]` + The index of the content part that the refusal text is added to. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `delta: string` - - `parameters: optional unknown` + The refusal text that is added. - - `strict: optional boolean` + - `item_id: string` - 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 ID of the output item that the refusal text is added to. - - `Custom object { name, type, allowed_callers, 3 more }` + - `output_index: number` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + The index of the output item that the refusal text is added to. - - `name: string` + - `sequence_number: number` - The name of the custom tool, used to identify it in tool calls. + The sequence number of this event. - - `type: "custom"` + - `type: "response.refusal.delta"` - The type of the custom tool. Always `custom`. + The type of the event. Always `response.refusal.delta`. - - `"custom"` + - `"response.refusal.delta"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `agent: optional object { agent_name }` - The tool invocation context(s). + The agent that owns this multi-agent streaming event. - - `"direct"` + - `agent_name: string` - - `"programmatic"` + The canonical name of the agent that produced this item. - - `defer_loading: optional boolean` + - `BetaResponseRefusalDoneEvent object { content_index, item_id, output_index, 4 more }` - Whether this tool should be deferred and discovered via tool search. + Emitted when refusal text is finalized. - - `description: optional string` + - `content_index: number` - Optional description of the custom tool, used to provide more context. + The index of the content part that the refusal text is finalized. - - `format: optional object { type } or object { definition, syntax, type }` + - `item_id: string` - The input format for the custom tool. Default is unconstrained text. + The ID of the output item that the refusal text is finalized. - - `Text object { type }` + - `output_index: number` - Unconstrained free-form text. + The index of the output item that the refusal text is finalized. - - `type: "text"` + - `refusal: string` - Unconstrained text format. Always `text`. + The refusal text that is finalized. - - `"text"` + - `sequence_number: number` - - `Grammar object { definition, syntax, type }` + The sequence number of this event. - A grammar defined by the user. + - `type: "response.refusal.done"` - - `definition: string` + The type of the event. Always `response.refusal.done`. - The grammar definition. + - `"response.refusal.done"` - - `syntax: "lark" or "regex"` + - `agent: optional object { agent_name }` - The syntax of the grammar definition. One of `lark` or `regex`. + The agent that owns this multi-agent streaming event. - - `"lark"` + - `agent_name: string` - - `"regex"` + The canonical name of the agent that produced this item. - - `type: "grammar"` + - `BetaResponseTextDeltaEvent object { content_index, delta, item_id, 5 more }` - Grammar format. Always `grammar`. + Emitted when there is an additional text delta. - - `"grammar"` + - `content_index: number` - - `type: "namespace"` + The index of the content part that the text delta was added to. - The type of the tool. Always `namespace`. + - `delta: string` - - `"namespace"` + The text delta that was added. - - `ToolSearch object { type, description, execution, parameters }` + - `item_id: string` - Hosted or BYOT tool search configuration for deferred tools. + The ID of the output item that the text delta was added to. - - `type: "tool_search"` + - `logprobs: array of object { token, logprob, top_logprobs }` - The type of the tool. Always `tool_search`. + The log probabilities of the tokens in the delta. - - `"tool_search"` + - `token: string` - - `description: optional string` + A possible text token. - Description shown to the model for a client-executed tool search tool. + - `logprob: number` - - `execution: optional "server" or "client"` + The log probability of this token. - Whether tool search is executed by the server or by the client. + - `top_logprobs: optional array of object { token, logprob }` - - `"server"` + The log probabilities of up to 20 of the most likely tokens. - - `"client"` + - `token: optional string` - - `parameters: optional unknown` + A possible text token. - Parameter schema for a client-executed tool search tool. + - `logprob: optional number` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + The log probability of this token. - 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). + - `output_index: number` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + The index of the output item that the text delta was added to. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `sequence_number: number` - - `"web_search_preview"` + The sequence number for this event. - - `"web_search_preview_2025_03_11"` + - `type: "response.output_text.delta"` - - `search_content_types: optional array of "text" or "image"` + The type of the event. Always `response.output_text.delta`. - - `"text"` + - `"response.output_text.delta"` - - `"image"` + - `agent: optional object { agent_name }` - - `search_context_size: optional "low" or "medium" or "high"` + The agent that owns this multi-agent streaming event. - 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. + - `agent_name: string` - - `"low"` + The canonical name of the agent that produced this item. - - `"medium"` + - `BetaResponseTextDoneEvent object { content_index, item_id, logprobs, 5 more }` - - `"high"` + Emitted when text content is finalized. - - `user_location: optional object { type, city, country, 2 more }` + - `content_index: number` - The user's location. + The index of the content part that the text content is finalized. - - `type: "approximate"` + - `item_id: string` - The type of location approximation. Always `approximate`. + The ID of the output item that the text content is finalized. - - `"approximate"` + - `logprobs: array of object { token, logprob, top_logprobs }` - - `city: optional string` + The log probabilities of the tokens in the delta. - Free text input for the city of the user, e.g. `San Francisco`. + - `token: string` - - `country: optional string` + A possible text token. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `logprob: number` - - `region: optional string` + The log probability of this token. - Free text input for the region of the user, e.g. `California`. + - `top_logprobs: optional array of object { token, logprob }` - - `timezone: optional string` + The log probabilities of up to 20 of the most likely tokens. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `token: optional string` - - `ApplyPatch object { type, allowed_callers }` + A possible text token. - Allows the assistant to create, delete, or update files using unified diffs. + - `logprob: optional number` - - `type: "apply_patch"` + The log probability of this token. - The type of the tool. Always `apply_patch`. + - `output_index: number` - - `"apply_patch"` + The index of the output item that the text content is finalized. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `sequence_number: number` - The tool invocation context(s). + The sequence number for this event. - - `"direct"` + - `text: string` - - `"programmatic"` + The text content that is finalized. - - `type: "tool_search_output"` + - `type: "response.output_text.done"` - The type of the item. Always `tool_search_output`. + The type of the event. Always `response.output_text.done`. - - `"tool_search_output"` + - `"response.output_text.done"` - `agent: optional object { agent_name }` - The agent that produced this item. + The agent that owns this multi-agent streaming event. - `agent_name: string` The canonical name of the agent that produced this item. - - `created_by: optional string` - - The identifier of the actor that created the item. - - - `AdditionalTools object { id, role, tools, 2 more }` + - `BetaResponseWebSearchCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - - `id: string` + Emitted when a web search call is completed. - The unique ID of the additional tools item. + - `item_id: string` - - `role: "unknown" or "user" or "assistant" or 5 more` + Unique ID for the output item associated with the web search call. - The role that provided the additional tools. + - `output_index: number` - - `"unknown"` + The index of the output item that the web search call is associated with. - - `"user"` + - `sequence_number: number` - - `"assistant"` + The sequence number of the web search call being processed. - - `"system"` + - `type: "response.web_search_call.completed"` - - `"critic"` + The type of the event. Always `response.web_search_call.completed`. - - `"discriminator"` + - `"response.web_search_call.completed"` - - `"developer"` + - `agent: optional object { agent_name }` - - `"tool"` + The agent that owns this multi-agent streaming event. - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + - `agent_name: string` - The additional tool definitions made available at this item. + The canonical name of the agent that produced this item. - - `Function object { name, parameters, strict, 5 more }` + - `BetaResponseWebSearchCallInProgressEvent object { item_id, output_index, sequence_number, 2 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). + Emitted when a web search call is initiated. - - `name: string` + - `item_id: string` - The name of the function to call. + Unique ID for the output item associated with the web search call. - - `parameters: map[unknown]` + - `output_index: number` - A JSON schema object describing the parameters of the function. + The index of the output item that the web search call is associated with. - - `strict: boolean` + - `sequence_number: number` - Whether strict parameter validation is enforced for this function tool. + The sequence number of the web search call being processed. - - `type: "function"` + - `type: "response.web_search_call.in_progress"` - The type of the function tool. Always `function`. + The type of the event. Always `response.web_search_call.in_progress`. - - `"function"` + - `"response.web_search_call.in_progress"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `agent: optional object { agent_name }` - The tool invocation context(s). + The agent that owns this multi-agent streaming event. - - `"direct"` + - `agent_name: string` - - `"programmatic"` + The canonical name of the agent that produced this item. - - `defer_loading: optional boolean` + - `BetaResponseWebSearchCallSearchingEvent object { item_id, output_index, sequence_number, 2 more }` - Whether this function is deferred and loaded via tool search. + Emitted when a web search call is executing. - - `description: optional string` + - `item_id: string` - A description of the function. Used by the model to determine whether or not to call the function. + Unique ID for the output item associated with the web search call. - - `output_schema: optional map[unknown]` + - `output_index: number` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The index of the output item that the web search call is associated with. - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `sequence_number: number` - 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 sequence number of the web search call being processed. - - `type: "file_search"` + - `type: "response.web_search_call.searching"` - The type of the file search tool. Always `file_search`. + The type of the event. Always `response.web_search_call.searching`. - - `"file_search"` + - `"response.web_search_call.searching"` - - `vector_store_ids: array of string` + - `agent: optional object { agent_name }` - The IDs of the vector stores to search. + The agent that owns this multi-agent streaming event. - - `filters: optional object { key, type, value } or object { filters, type }` + - `agent_name: string` - A filter to apply. + The canonical name of the agent that produced this item. - - `ComparisonFilter object { key, type, value }` + - `BetaResponseImageGenCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + Emitted when an image generation tool call has completed and the final image is available. - - `key: string` + - `item_id: string` - The key to compare against the value. + The unique identifier of the image generation item being processed. - - `type: "eq" or "ne" or "gt" or 5 more` + - `output_index: number` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The index of the output item in the response's output array. - - `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 + - `sequence_number: number` - - `"eq"` + The sequence number of this event. - - `"ne"` + - `type: "response.image_generation_call.completed"` - - `"gt"` + The type of the event. Always 'response.image_generation_call.completed'. - - `"gte"` + - `"response.image_generation_call.completed"` - - `"lt"` + - `agent: optional object { agent_name }` - - `"lte"` + The agent that owns this multi-agent streaming event. - - `"in"` + - `agent_name: string` - - `"nin"` + The canonical name of the agent that produced this item. - - `value: string or number or boolean or array of string or number` + - `BetaResponseImageGenCallGeneratingEvent object { item_id, output_index, sequence_number, 2 more }` - The value to compare against the attribute key; supports string, number, or boolean types. + Emitted when an image generation tool call is actively generating an image (intermediate state). - - `string` + - `item_id: string` - - `number` + The unique identifier of the image generation item being processed. - - `boolean` + - `output_index: number` - - `array of string or number` + The index of the output item in the response's output array. - - `string` + - `sequence_number: number` - - `number` + The sequence number of the image generation item being processed. - - `CompoundFilter object { filters, type }` + - `type: "response.image_generation_call.generating"` - Combine multiple filters using `and` or `or`. + The type of the event. Always 'response.image_generation_call.generating'. - - `filters: array of object { key, type, value } or unknown` + - `"response.image_generation_call.generating"` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `agent: optional object { agent_name }` - - `ComparisonFilter object { key, type, value }` + The agent that owns this multi-agent streaming event. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `agent_name: string` - - `key: string` + The canonical name of the agent that produced this item. - The key to compare against the value. + - `BetaResponseImageGenCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` - - `type: "eq" or "ne" or "gt" or 5 more` + Emitted when an image generation tool call is in progress. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `item_id: string` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + The unique identifier of the image generation item being processed. - - `"eq"` + - `output_index: number` - - `"ne"` + The index of the output item in the response's output array. - - `"gt"` + - `sequence_number: number` - - `"gte"` + The sequence number of the image generation item being processed. - - `"lt"` + - `type: "response.image_generation_call.in_progress"` - - `"lte"` + The type of the event. Always 'response.image_generation_call.in_progress'. - - `"in"` + - `"response.image_generation_call.in_progress"` - - `"nin"` + - `agent: optional object { agent_name }` - - `value: string or number or boolean or array of string or number` + The agent that owns this multi-agent streaming event. - The value to compare against the attribute key; supports string, number, or boolean types. + - `agent_name: string` - - `string` + The canonical name of the agent that produced this item. - - `number` + - `BetaResponseImageGenCallPartialImageEvent object { item_id, output_index, partial_image_b64, 4 more }` - - `boolean` + Emitted when a partial image is available during image generation streaming. - - `array of string or number` + - `item_id: string` - - `string` + The unique identifier of the image generation item being processed. - - `number` + - `output_index: number` - - `unknown` + The index of the output item in the response's output array. - - `type: "and" or "or"` + - `partial_image_b64: string` - Type of operation: `and` or `or`. + Base64-encoded partial image data, suitable for rendering as an image. - - `"and"` + - `partial_image_index: number` - - `"or"` + 0-based index for the partial image (backend is 1-based, but this is 0-based for the user). - - `max_num_results: optional number` + - `sequence_number: number` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + The sequence number of the image generation item being processed. - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `type: "response.image_generation_call.partial_image"` - Ranking options for search. + The type of the event. Always 'response.image_generation_call.partial_image'. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `"response.image_generation_call.partial_image"` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `agent: optional object { agent_name }` - - `embedding_weight: number` + The agent that owns this multi-agent streaming event. - The weight of the embedding in the reciprocal ranking fusion. + - `agent_name: string` - - `text_weight: number` + The canonical name of the agent that produced this item. - The weight of the text in the reciprocal ranking fusion. + - `BetaResponseMcpCallArgumentsDeltaEvent object { delta, item_id, output_index, 3 more }` - - `ranker: optional "auto" or "default-2024-11-15"` + Emitted when there is a delta (partial update) to the arguments of an MCP tool call. - The ranker to use for the file search. + - `delta: string` - - `"auto"` + A JSON string containing the partial update to the arguments for the MCP tool call. - - `"default-2024-11-15"` + - `item_id: string` - - `score_threshold: optional number` + The unique identifier of the MCP tool call item being processed. - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + - `output_index: number` - - `Computer object { type }` + The index of the output item in the response's output array. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `sequence_number: number` - - `type: "computer"` + The sequence number of this event. - The type of the computer tool. Always `computer`. + - `type: "response.mcp_call_arguments.delta"` - - `"computer"` + The type of the event. Always 'response.mcp_call_arguments.delta'. - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `"response.mcp_call_arguments.delta"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `agent: optional object { agent_name }` - - `display_height: number` + The agent that owns this multi-agent streaming event. - The height of the computer display. + - `agent_name: string` - - `display_width: number` + The canonical name of the agent that produced this item. - The width of the computer display. + - `BetaResponseMcpCallArgumentsDoneEvent object { arguments, item_id, output_index, 3 more }` - - `environment: "windows" or "mac" or "linux" or 2 more` + Emitted when the arguments for an MCP tool call are finalized. - The type of computer environment to control. + - `arguments: string` - - `"windows"` + A JSON string containing the finalized arguments for the MCP tool call. - - `"mac"` + - `item_id: string` - - `"linux"` + The unique identifier of the MCP tool call item being processed. - - `"ubuntu"` + - `output_index: number` - - `"browser"` + The index of the output item in the response's output array. - - `type: "computer_use_preview"` + - `sequence_number: number` - The type of the computer use tool. Always `computer_use_preview`. + The sequence number of this event. - - `"computer_use_preview"` + - `type: "response.mcp_call_arguments.done"` - - `WebSearch object { type, filters, search_context_size, user_location }` + The type of the event. Always 'response.mcp_call_arguments.done'. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + - `"response.mcp_call_arguments.done"` - - `type: "web_search" or "web_search_2025_08_26"` + - `agent: optional object { agent_name }` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + The agent that owns this multi-agent streaming event. - - `"web_search"` + - `agent_name: string` - - `"web_search_2025_08_26"` + The canonical name of the agent that produced this item. - - `filters: optional object { allowed_domains }` + - `BetaResponseMcpCallCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - Filters for the search. + Emitted when an MCP tool call has completed successfully. - - `allowed_domains: optional array of string` + - `item_id: string` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + The ID of the MCP tool call item that completed. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `output_index: number` - - `search_context_size: optional "low" or "medium" or "high"` + The index of the output item that completed. - 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. + - `sequence_number: number` - - `"low"` + The sequence number of this event. - - `"medium"` + - `type: "response.mcp_call.completed"` - - `"high"` + The type of the event. Always 'response.mcp_call.completed'. - - `user_location: optional object { city, country, region, 2 more }` + - `"response.mcp_call.completed"` - The approximate location of the user. + - `agent: optional object { agent_name }` - - `city: optional string` + The agent that owns this multi-agent streaming event. - Free text input for the city of the user, e.g. `San Francisco`. + - `agent_name: string` - - `country: optional string` + The canonical name of the agent that produced this item. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `BetaResponseMcpCallFailedEvent object { item_id, output_index, sequence_number, 2 more }` - - `region: optional string` + Emitted when an MCP tool call has failed. - Free text input for the region of the user, e.g. `California`. + - `item_id: string` - - `timezone: optional string` + The ID of the MCP tool call item that failed. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `output_index: number` - - `type: optional "approximate"` + The index of the output item that failed. - The type of location approximation. Always `approximate`. + - `sequence_number: number` - - `"approximate"` + The sequence number of this event. - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `type: "response.mcp_call.failed"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + The type of the event. Always 'response.mcp_call.failed'. - - `server_label: string` + - `"response.mcp_call.failed"` - A label for this MCP server, used to identify it in tool calls. + - `agent: optional object { agent_name }` - - `type: "mcp"` + The agent that owns this multi-agent streaming event. - The type of the MCP tool. Always `mcp`. + - `agent_name: string` - - `"mcp"` + The canonical name of the agent that produced this item. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `BetaResponseMcpCallInProgressEvent object { item_id, output_index, sequence_number, 2 more }` - The tool invocation context(s). + Emitted when an MCP tool call is in progress. - - `"direct"` + - `item_id: string` - - `"programmatic"` + The unique identifier of the MCP tool call item being processed. - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `output_index: number` - List of allowed tool names or a filter object. + The index of the output item in the response's output array. - - `McpAllowedTools = array of string` + - `sequence_number: number` - A string array of allowed tool names + The sequence number of this event. - - `McpToolFilter object { read_only, tool_names }` + - `type: "response.mcp_call.in_progress"` - A filter object to specify which tools are allowed. + The type of the event. Always 'response.mcp_call.in_progress'. - - `read_only: optional boolean` + - `"response.mcp_call.in_progress"` - 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. + - `agent: optional object { agent_name }` - - `tool_names: optional array of string` + The agent that owns this multi-agent streaming event. - List of allowed tool names. + - `agent_name: string` - - `authorization: optional string` + The canonical name of the agent that produced this item. - 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. + - `BetaResponseMcpListToolsCompletedEvent object { item_id, output_index, sequence_number, 2 more }` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + Emitted when the list of available MCP tools has been successfully retrieved. - 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). + - `item_id: string` - Currently supported `connector_id` values are: + The ID of the MCP tool call item that produced this output. - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `output_index: number` - - `"connector_dropbox"` + The index of the output item that was processed. - - `"connector_gmail"` + - `sequence_number: number` - - `"connector_googlecalendar"` + The sequence number of this event. - - `"connector_googledrive"` + - `type: "response.mcp_list_tools.completed"` - - `"connector_microsoftteams"` + The type of the event. Always 'response.mcp_list_tools.completed'. - - `"connector_outlookcalendar"` + - `"response.mcp_list_tools.completed"` - - `"connector_outlookemail"` + - `agent: optional object { agent_name }` - - `"connector_sharepoint"` + The agent that owns this multi-agent streaming event. - - `defer_loading: optional boolean` + - `agent_name: string` - Whether this MCP tool is deferred and discovered via tool search. + The canonical name of the agent that produced this item. - - `headers: optional map[string]` + - `BetaResponseMcpListToolsFailedEvent object { item_id, output_index, sequence_number, 2 more }` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + Emitted when the attempt to list available MCP tools has failed. - - `require_approval: optional object { always, never } or "always" or "never"` + - `item_id: string` - Specify which of the MCP server's tools require approval. + The ID of the MCP tool call item that failed. - - `McpToolApprovalFilter object { always, never }` + - `output_index: number` - 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 index of the output item that failed. - - `always: optional object { read_only, tool_names }` + - `sequence_number: number` - A filter object to specify which tools are allowed. + The sequence number of this event. - - `read_only: optional boolean` + - `type: "response.mcp_list_tools.failed"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The type of the event. Always 'response.mcp_list_tools.failed'. - - `tool_names: optional array of string` + - `"response.mcp_list_tools.failed"` - List of allowed tool names. + - `agent: optional object { agent_name }` - - `never: optional object { read_only, tool_names }` + The agent that owns this multi-agent streaming event. - A filter object to specify which tools are allowed. + - `agent_name: string` - - `read_only: optional boolean` + The canonical name of the agent that produced this item. - 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. + - `BetaResponseMcpListToolsInProgressEvent object { item_id, output_index, sequence_number, 2 more }` - - `tool_names: optional array of string` + Emitted when the system is in the process of retrieving the list of available MCP tools. - List of allowed tool names. + - `item_id: string` - - `McpToolApprovalSetting = "always" or "never"` + The ID of the MCP tool call item that is being processed. - 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. + - `output_index: number` - - `"always"` + The index of the output item that is being processed. - - `"never"` + - `sequence_number: number` - - `server_description: optional string` + The sequence number of this event. - Optional description of the MCP server, used to provide more context. + - `type: "response.mcp_list_tools.in_progress"` - - `server_url: optional string` + The type of the event. Always 'response.mcp_list_tools.in_progress'. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `"response.mcp_list_tools.in_progress"` - - `tunnel_id: optional string` + - `agent: optional object { agent_name }` - 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 agent that owns this multi-agent streaming event. - - `CodeInterpreter object { container, type, allowed_callers }` + - `agent_name: string` - A tool that runs Python code to help generate a response to a prompt. + The canonical name of the agent that produced this item. - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `BetaResponseOutputTextAnnotationAddedEvent object { annotation, annotation_index, content_index, 5 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. + Emitted when an annotation is added to output text content. - - `string` + - `annotation: unknown` - The container ID. + The annotation object being added. (See annotation schema for details.) - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `annotation_index: number` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + The index of the annotation within the content part. - - `type: "auto"` + - `content_index: number` - Always `auto`. + The index of the content part within the output item. - - `"auto"` + - `item_id: string` - - `file_ids: optional array of string` + The unique identifier of the item to which the annotation is being added. - An optional list of uploaded files to make available to your code. + - `output_index: number` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + The index of the output item in the response's output array. - The memory limit for the code interpreter container. + - `sequence_number: number` - - `"1g"` + The sequence number of this event. - - `"4g"` + - `type: "response.output_text.annotation.added"` - - `"16g"` + The type of the event. Always 'response.output_text.annotation.added'. - - `"64g"` + - `"response.output_text.annotation.added"` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `agent: optional object { agent_name }` - Network access policy for the container. + The agent that owns this multi-agent streaming event. - - `BetaContainerNetworkPolicyDisabled object { type }` + - `agent_name: string` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + The canonical name of the agent that produced this item. - - `type: "code_interpreter"` + - `BetaResponseQueuedEvent object { response, sequence_number, type, agent }` - The type of the code interpreter tool. Always `code_interpreter`. + Emitted when a response is queued and waiting to be processed. - - `"code_interpreter"` + - `response: BetaResponse` - - `allowed_callers: optional array of "direct" or "programmatic"` + The full response object that is queued. - The tool invocation context(s). + - `sequence_number: number` - - `"direct"` + The sequence number for this event. - - `"programmatic"` + - `type: "response.queued"` - - `ProgrammaticToolCalling object { type }` + The type of the event. Always 'response.queued'. - - `type: "programmatic_tool_calling"` + - `"response.queued"` - The type of the tool. Always `programmatic_tool_calling`. + - `agent: optional object { agent_name }` - - `"programmatic_tool_calling"` + The agent that owns this multi-agent streaming event. - - `ImageGeneration object { type, action, background, 9 more }` + - `agent_name: string` - A tool that generates images using the GPT image models. + The canonical name of the agent that produced this item. - - `type: "image_generation"` + - `BetaResponseCustomToolCallInputDeltaEvent object { delta, item_id, output_index, 3 more }` - The type of the image generation tool. Always `image_generation`. + Event representing a delta (partial update) to the input of a custom tool call. - - `"image_generation"` + - `delta: string` - - `action: optional "generate" or "edit" or "auto"` + The incremental input data (delta) for the custom tool call. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `item_id: string` - - `"generate"` + Unique identifier for the API item associated with this event. - - `"edit"` + - `output_index: number` - - `"auto"` + The index of the output this delta applies to. - - `background: optional "transparent" or "opaque" or "auto"` + - `sequence_number: number` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + The sequence number of this event. - - `"transparent"` + - `type: "response.custom_tool_call_input.delta"` - - `"opaque"` + The event type identifier. - - `"auto"` + - `"response.custom_tool_call_input.delta"` - - `input_fidelity: optional "high" or "low"` + - `agent: optional object { agent_name }` - 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 agent that owns this multi-agent streaming event. - - `"high"` + - `agent_name: string` - - `"low"` + The canonical name of the agent that produced this item. - - `input_image_mask: optional object { file_id, image_url }` + - `BetaResponseCustomToolCallInputDoneEvent object { input, item_id, output_index, 3 more }` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + Event indicating that input for a custom tool call is complete. - - `file_id: optional string` + - `input: string` - File ID for the mask image. + The complete input data for the custom tool call. - - `image_url: optional string` + - `item_id: string` - Base64-encoded mask image. + Unique identifier for the API item associated with this event. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `output_index: number` - The image generation model to use. Default: `gpt-image-1`. + The index of the output this event applies to. - - `string` + - `sequence_number: number` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + The sequence number of this event. - The image generation model to use. Default: `gpt-image-1`. + - `type: "response.custom_tool_call_input.done"` - - `"gpt-image-1"` + The event type identifier. - - `"gpt-image-1-mini"` + - `"response.custom_tool_call_input.done"` - - `"gpt-image-1.5"` + - `agent: optional object { agent_name }` - - `moderation: optional "auto" or "low"` + The agent that owns this multi-agent streaming event. - Moderation level for the generated image. Default: `auto`. + - `agent_name: string` - - `"auto"` + The canonical name of the agent that produced this item. - - `"low"` + - `BetaResponseInjectCreatedEvent object { response_id, sequence_number, type, stream_id }` - - `output_compression: optional number` + Emitted when all injected input items were validated and committed to the + active response. - Compression level for the output image. Default: 100. + - `response_id: string` - - `output_format: optional "png" or "webp" or "jpeg"` + The ID of the response that accepted the input. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `sequence_number: number` - - `"png"` + The sequence number for this event. - - `"webp"` + - `type: "response.inject.created"` - - `"jpeg"` + The event discriminator. Always `response.inject.created`. - - `partial_images: optional number` + - `"response.inject.created"` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `stream_id: optional string` - - `quality: optional "low" or "medium" or "high" or "auto"` + The multiplexed WebSocket stream that emitted the event. This field is + present only when WebSocket multiplexing is enabled separately. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `BetaResponseInjectFailedEvent object { error, input, response_id, 3 more }` - - `"low"` + Emitted when injected input could not be committed to a response. The event + returns the uncommitted raw input so the client can retry it in another + response when appropriate. - - `"medium"` + - `error: object { code, message }` - - `"high"` + Information about why the input was not committed. - - `"auto"` + - `code: "response_already_completed" or "response_not_found"` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + A machine-readable error code. - 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`. + - `"response_already_completed"` - - `string` + - `"response_not_found"` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `message: 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`. + A human-readable description of the error. - - `"1024x1024"` + - `input: array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - - `"1024x1536"` + The raw input items that were not committed. - - `"1536x1024"` + - `BetaEasyInputMessage object { content, role, phase, type }` - - `"auto"` + 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. - - `LocalShell object { type }` + - `Message object { content, role, agent, 2 more }` - A tool that allows the model to execute shell commands in a local environment. + 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: "local_shell"` + - `content: BetaResponseInputMessageContentList` - The type of the local shell tool. Always `local_shell`. + A list of one or many input items to the model, containing different content + types. - - `"local_shell"` + - `role: "user" or "system" or "developer"` - - `Shell object { type, allowed_callers, environment }` + The role of the message input. One of `user`, `system`, or `developer`. - A tool that allows the model to execute shell commands. + - `"user"` - - `type: "shell"` + - `"system"` - The type of the shell tool. Always `shell`. + - `"developer"` - - `"shell"` + - `agent: optional object { agent_name }` - - `allowed_callers: optional array of "direct" or "programmatic"` + The agent that produced this item. - The tool invocation context(s). + - `agent_name: string` - - `"direct"` + The canonical name of the agent that produced this item. - - `"programmatic"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `"in_progress"` - - `BetaLocalEnvironment object { type, skills }` + - `"completed"` - - `BetaContainerReference object { container_id, type }` + - `"incomplete"` - - `Custom object { name, type, allowed_callers, 3 more }` + - `type: optional "message"` - 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 message input. Always set to `message`. - - `name: string` + - `"message"` - The name of the custom tool, used to identify it in tool calls. + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - - `type: "custom"` + An output message from the model. - The type of the custom tool. Always `custom`. + - `FileSearchCall object { id, queries, status, 3 more }` - - `"custom"` + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `id: string` - The tool invocation context(s). + The unique ID of the file search tool call. - - `"direct"` + - `queries: array of string` - - `"programmatic"` + The queries used to search for files. - - `defer_loading: optional boolean` + - `status: "in_progress" or "searching" or "completed" or 2 more` - Whether this tool should be deferred and discovered via tool search. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `description: optional string` + - `"in_progress"` - Optional description of the custom tool, used to provide more context. + - `"searching"` - - `format: optional object { type } or object { definition, syntax, type }` + - `"completed"` - The input format for the custom tool. Default is unconstrained text. + - `"incomplete"` - - `Text object { type }` + - `"failed"` - Unconstrained free-form text. + - `type: "file_search_call"` - - `type: "text"` + The type of the file search tool call. Always `file_search_call`. - Unconstrained text format. Always `text`. + - `"file_search_call"` - - `"text"` + - `agent: optional object { agent_name }` - - `Grammar object { definition, syntax, type }` + The agent that produced this item. - A grammar defined by the user. + - `agent_name: string` - - `definition: string` + The canonical name of the agent that produced this item. - The grammar definition. + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `syntax: "lark" or "regex"` + The results of the file search tool call. - The syntax of the grammar definition. One of `lark` or `regex`. + - `attributes: optional map[string or number or boolean]` - - `"lark"` + 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. - - `"regex"` + - `string` - - `type: "grammar"` + - `number` - Grammar format. Always `grammar`. + - `boolean` - - `"grammar"` + - `file_id: optional string` - - `Namespace object { description, name, tools, type }` + The unique ID of the file. - Groups function/custom tools under a shared namespace. + - `filename: optional string` - - `description: string` + The name of the file. - A description of the namespace shown to the model. + - `score: optional number` - - `name: string` + The relevance score of the file - a value between 0 and 1. - The namespace name used in tool calls (for example, `crm`). + - `text: optional string` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + The text that was retrieved from the file. - The function/custom tools available inside this namespace. + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - - `Function object { name, type, allowed_callers, 5 more }` + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - - `name: string` + - `id: string` - - `type: "function"` + The unique ID of the computer call. - - `"function"` + - `call_id: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + An identifier used when responding to the tool call with output. - The tool invocation context(s). + - `pending_safety_checks: array of object { id, code, message }` - - `"direct"` + The pending safety checks for the computer call. - - `"programmatic"` + - `id: string` - - `defer_loading: optional boolean` + The ID of the pending safety check. - Whether this function should be deferred and discovered via tool search. + - `code: optional string` - - `description: optional string` + The type of the pending safety check. - - `output_schema: optional map[unknown]` + - `message: optional string` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + Details about the pending safety check. - - `parameters: optional unknown` + - `status: "in_progress" or "completed" or "incomplete"` - - `strict: optional boolean` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - 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 }` + - `"completed"` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `"incomplete"` - - `name: string` + - `type: "computer_call"` - The name of the custom tool, used to identify it in tool calls. + The type of the computer call. Always `computer_call`. - - `type: "custom"` + - `"computer_call"` - The type of the custom tool. Always `custom`. + - `action: optional BetaComputerAction` - - `"custom"` + A click action. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `actions: optional BetaComputerActionList` - The tool invocation context(s). + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `"direct"` + - `agent: optional object { agent_name }` - - `"programmatic"` + The agent that produced this item. - - `defer_loading: optional boolean` + - `agent_name: string` - Whether this tool should be deferred and discovered via tool search. + The canonical name of the agent that produced this item. - - `description: optional string` + - `ComputerCallOutput object { call_id, output, type, 4 more }` - Optional description of the custom tool, used to provide more context. + The output of a computer tool call. - - `format: optional object { type } or object { definition, syntax, type }` + - `call_id: string` - The input format for the custom tool. Default is unconstrained text. + The ID of the computer tool call that produced the output. - - `Text object { type }` + - `output: BetaResponseComputerToolCallOutputScreenshot` - Unconstrained free-form text. + A computer screenshot image used with the computer use tool. - - `type: "text"` + - `type: "computer_call_output"` - Unconstrained text format. Always `text`. + The type of the computer tool call output. Always `computer_call_output`. - - `"text"` + - `"computer_call_output"` - - `Grammar object { definition, syntax, type }` + - `id: optional string` - A grammar defined by the user. + The ID of the computer tool call output. - - `definition: string` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - The grammar definition. + The safety checks reported by the API that have been acknowledged by the developer. - - `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"` + - `agent: optional object { agent_name }` - - `type: "namespace"` + The agent that produced this item. - The type of the tool. Always `namespace`. + - `agent_name: string` - - `"namespace"` + The canonical name of the agent that produced this item. - - `ToolSearch object { type, description, execution, parameters }` + - `status: optional "in_progress" or "completed" or "incomplete"` - Hosted or BYOT tool search configuration for deferred tools. + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - `type: "tool_search"` + - `"in_progress"` - The type of the tool. Always `tool_search`. + - `"completed"` - - `"tool_search"` + - `"incomplete"` - - `description: optional string` + - `WebSearchCall object { id, action, status, 2 more }` - Description shown to the model for a client-executed tool search tool. + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `execution: optional "server" or "client"` + - `id: string` - Whether tool search is executed by the server or by the client. + The unique ID of the web search tool call. - - `"server"` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `"client"` + 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). - - `parameters: optional unknown` + - `Search object { type, queries, query, sources }` - Parameter schema for a client-executed tool search tool. + Action type "search" - Performs a web search query. - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `type: "search"` - 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 action type. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `"search"` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `queries: optional array of string` - - `"web_search_preview"` + The search queries. - - `"web_search_preview_2025_03_11"` + - `query: optional string` - - `search_content_types: optional array of "text" or "image"` + The search query. - - `"text"` + - `sources: optional array of object { type, url }` - - `"image"` + The sources used in the search. - - `search_context_size: optional "low" or "medium" or "high"` + - `type: "url"` - High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. + The type of source. Always `url`. - - `"low"` + - `"url"` - - `"medium"` + - `url: string` - - `"high"` + The URL of the source. - - `user_location: optional object { type, city, country, 2 more }` + - `OpenPage object { type, url }` - The user's location. + Action type "open_page" - Opens a specific URL from search results. - - `type: "approximate"` + - `type: "open_page"` - The type of location approximation. Always `approximate`. + The action type. - - `"approximate"` + - `"open_page"` - - `city: optional string` + - `url: optional string` - Free text input for the city of the user, e.g. `San Francisco`. + The URL opened by the model. - - `country: optional string` + - `FindInPage object { pattern, type, url }` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `region: optional string` + - `pattern: string` - Free text input for the region of the user, e.g. `California`. + The pattern or text to search for within the page. - - `timezone: optional string` + - `type: "find_in_page"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The action type. - - `ApplyPatch object { type, allowed_callers }` + - `"find_in_page"` - Allows the assistant to create, delete, or update files using unified diffs. + - `url: string` - - `type: "apply_patch"` + The URL of the page searched for the pattern. - The type of the tool. Always `apply_patch`. + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `"apply_patch"` + 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"` - - `type: "additional_tools"` + - `type: "web_search_call"` - The type of the item. Always `additional_tools`. + The type of the web search tool call. Always `web_search_call`. - - `"additional_tools"` + - `"web_search_call"` - `agent: optional object { agent_name }` @@ -202597,36 +203492,32 @@ Returns a list of input items for a given response. The canonical name of the agent that produced this item. - - `Reasoning object { id, summary, type, 4 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). + - `FunctionCall object { arguments, call_id, name, 6 more }` - - `id: string` + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - The unique identifier of the reasoning content. + - `arguments: string` - - `summary: array of object { text, type }` + A JSON string of the arguments to pass to the function. - Reasoning summary content. + - `call_id: string` - - `text: string` + The unique ID of the function tool call generated by the model. - A summary of the reasoning output from the model so far. + - `name: string` - - `type: "summary_text"` + The name of the function to run. - The type of the object. Always `summary_text`. + - `type: "function_call"` - - `"summary_text"` + The type of the function tool call. Always `function_call`. - - `type: "reasoning"` + - `"function_call"` - The type of the object. Always `reasoning`. + - `id: optional string` - - `"reasoning"` + The unique ID of the function tool call. - `agent: optional object { agent_name }` @@ -202636,25 +203527,29 @@ Returns a list of input items for a given response. The canonical name of the agent that produced this item. - - `content: optional array of object { text, type }` + - `caller: optional object { type } or object { caller_id, type }` - Reasoning text content. + The execution context that produced this tool call. - - `text: string` + - `Direct object { type }` - The reasoning text from the model. + - `type: "direct"` - - `type: "reasoning_text"` + - `"direct"` - The type of the reasoning text. Always `reasoning_text`. + - `Program object { caller_id, type }` - - `"reasoning_text"` + - `caller_id: string` - - `encrypted_content: optional string` + The call ID of the program item that produced this tool call. - 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: "program"` + + - `"program"` + + - `namespace: optional string` + + The namespace of the function to run. - `status: optional "in_progress" or "completed" or "incomplete"` @@ -202667,29 +203562,47 @@ Returns a list of input items for a given response. - `"incomplete"` - - `Program object { id, call_id, code, 3 more }` - - - `id: string` + - `FunctionCallOutput object { call_id, output, type, 4 more }` - The unique ID of the program item. + The output of a function tool call. - `call_id: string` - The stable call ID of the program item. + The unique ID of the function tool call generated by the model. - - `code: string` + - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - The JavaScript source executed by programmatic tool calling. + Text, image, or file output of the function tool call. - - `fingerprint: string` + - `string` - Opaque program replay fingerprint that must be round-tripped. + A JSON string of the output of the function tool call. - - `type: "program"` + - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - The type of the item. Always `program`. + An array of content outputs (text, image, file) for the function tool call. - - `"program"` + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + + A text input to the model. + + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](/docs/guides/vision) + + - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` + + A file input to the model. + + - `type: "function_call_output"` + + The type of the function tool call output. Always `function_call_output`. + + - `"function_call_output"` + + - `id: optional string` + + The unique ID of the function tool call output. Populated when this item is returned via API. - `agent: optional object { agent_name }` @@ -202699,59 +203612,87 @@ Returns a list of input items for a given response. The canonical name of the agent that produced this item. - - `ProgramOutput object { id, call_id, result, 3 more }` + - `caller: optional object { type } or object { caller_id, type }` - - `id: string` + The execution context that produced this tool call. - The unique ID of the program output item. + - `Direct object { type }` - - `call_id: string` + - `type: "direct"` - The call ID of the program item. + The caller type. Always `direct`. - - `result: string` + - `"direct"` - The result produced by the program item. + - `Program object { caller_id, type }` - - `status: "completed" or "incomplete"` + - `caller_id: string` - The terminal status of the program output item. + 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"` - - `type: "program_output"` + - `AgentMessage object { author, content, recipient, 3 more }` - The type of the item. Always `program_output`. + A message routed between agents. - - `"program_output"` + - `author: string` - - `agent: optional object { agent_name }` + The sending agent identity. - The agent that produced this item. + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - - `agent_name: string` + Plaintext, image, or encrypted content sent between agents. - The canonical name of the agent that produced this item. + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - - `Compaction object { id, encrypted_content, type, 2 more }` + A text input to the model. - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - - `id: string` + An image input to the model. Learn about [image inputs](/docs/guides/vision) - The unique ID of the compaction item. + - `EncryptedContent object { encrypted_content, type }` + + Opaque encrypted content that Responses API decrypts inside trusted model execution. - `encrypted_content: string` - The encrypted content that was produced by compaction. + Opaque encrypted content. - - `type: "compaction"` + - `type: "encrypted_content"` - The type of the item. Always `compaction`. + The type of the input item. Always `encrypted_content`. - - `"compaction"` + - `"encrypted_content"` + + - `recipient: string` + + The destination agent identity. + + - `type: "agent_message"` + + The item type. Always `agent_message`. + + - `"agent_message"` + + - `id: optional string` + + The unique ID of this agent message item. - `agent: optional object { agent_name }` @@ -202761,39 +203702,41 @@ Returns a list of input items for a given response. The canonical name of the agent that produced this item. - - `created_by: optional string` + - `MultiAgentCall object { action, arguments, call_id, 3 more }` - The identifier of the actor that created the item. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `ImageGenerationCall object { id, result, status, 2 more }` + The multi-agent action that was executed. - An image generation request made by the model. + - `"spawn_agent"` - - `id: string` + - `"interrupt_agent"` - The unique ID of the image generation call. + - `"list_agents"` - - `result: string` + - `"send_message"` - The generated image encoded in base64. + - `"followup_task"` - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `"wait_agent"` - The status of the image generation call. + - `arguments: string` - - `"in_progress"` + The action arguments as a JSON string. - - `"completed"` + - `call_id: string` - - `"generating"` + The unique ID linking this call to its output. - - `"failed"` + - `type: "multi_agent_call"` - - `type: "image_generation_call"` + The item type. Always `multi_agent_call`. - The type of the image generation call. Always `image_generation_call`. + - `"multi_agent_call"` - - `"image_generation_call"` + - `id: optional string` + + The unique ID of this multi-agent call. - `agent: optional object { agent_name }` @@ -202803,140 +203746,127 @@ Returns a list of input items for a given response. The canonical name of the agent that produced this item. - - `CodeInterpreterCall object { id, code, container_id, 4 more }` - - A tool call to run code. - - - `id: string` - - The unique ID of the code interpreter tool call. - - - `code: string` - - The code to run, or null if not available. - - - `container_id: string` + - `MultiAgentCallOutput object { action, call_id, output, 3 more }` - The ID of the container used to run the code. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `outputs: array of object { logs, type } or object { type, url }` + The multi-agent action that produced this result. - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `"spawn_agent"` - - `Logs object { logs, type }` + - `"interrupt_agent"` - The logs output from the code interpreter. + - `"list_agents"` - - `logs: string` + - `"send_message"` - The logs output from the code interpreter. + - `"followup_task"` - - `type: "logs"` + - `"wait_agent"` - The type of the output. Always `logs`. + - `call_id: string` - - `"logs"` + The unique ID of the multi-agent call. - - `Image object { type, url }` + - `output: array of object { text, type, annotations }` - The image output from the code interpreter. + Text output returned by the multi-agent action. - - `type: "image"` + - `text: string` - The type of the output. Always `image`. + The text content. - - `"image"` + - `type: "output_text"` - - `url: string` + The content type. Always `output_text`. - The URL of the image output from the code interpreter. + - `"output_text"` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `annotations: optional 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 }` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + Citations associated with the text content. - - `"in_progress"` + - `FileCitation object { file_id, filename, index, type }` - - `"completed"` + - `file_id: string` - - `"incomplete"` + The ID of the file. - - `"interpreting"` + - `filename: string` - - `"failed"` + The filename of the file cited. - - `type: "code_interpreter_call"` + - `index: number` - The type of the code interpreter tool call. Always `code_interpreter_call`. + The index of the file in the list of files. - - `"code_interpreter_call"` + - `type: "file_citation"` - - `agent: optional object { agent_name }` + The citation type. Always `file_citation`. - The agent that produced this item. + - `"file_citation"` - - `agent_name: string` + - `URLCitation object { end_index, start_index, title, 2 more }` - The canonical name of the agent that produced this item. + - `end_index: number` - - `LocalShellCall object { id, action, call_id, 3 more }` + The index of the last character of the citation in the message. - A tool call to run a command on the local shell. + - `start_index: number` - - `id: string` + The index of the first character of the citation in the message. - The unique ID of the local shell call. + - `title: string` - - `action: object { command, env, type, 3 more }` + The title of the cited resource. - Execute a shell command on the server. + - `type: "url_citation"` - - `command: array of string` + The citation type. Always `url_citation`. - The command to run. + - `"url_citation"` - - `env: map[string]` + - `url: string` - Environment variables to set for the command. + The URL of the cited resource. - - `type: "exec"` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - The type of the local shell action. Always `exec`. + - `container_id: string` - - `"exec"` + The ID of the container. - - `timeout_ms: optional number` + - `end_index: number` - Optional timeout in milliseconds for the command. + The index of the last character of the citation in the message. - - `user: optional string` + - `file_id: string` - Optional user to run the command as. + The ID of the container file. - - `working_directory: optional string` + - `filename: string` - Optional working directory to run the command in. + The filename of the container file cited. - - `call_id: string` + - `start_index: number` - The unique ID of the local shell tool call generated by the model. + The index of the first character of the citation in the message. - - `status: "in_progress" or "completed" or "incomplete"` + - `type: "container_file_citation"` - The status of the local shell call. + The citation type. Always `container_file_citation`. - - `"in_progress"` + - `"container_file_citation"` - - `"completed"` + - `type: "multi_agent_call_output"` - - `"incomplete"` + The item type. Always `multi_agent_call_output`. - - `type: "local_shell_call"` + - `"multi_agent_call_output"` - The type of the local shell call. Always `local_shell_call`. + - `id: optional string` - - `"local_shell_call"` + The unique ID of this multi-agent call output. - `agent: optional object { agent_name }` @@ -202946,23 +203876,21 @@ Returns a list of input items for a given response. The canonical name of the agent that produced this item. - - `LocalShellCallOutput object { id, output, type, 2 more }` - - The output of a local shell tool call. + - `ToolSearchCall object { arguments, type, id, 4 more }` - - `id: string` + - `arguments: unknown` - The unique ID of the local shell tool call generated by the model. + The arguments supplied to the tool search call. - - `output: string` + - `type: "tool_search_call"` - A JSON string of the output of the local shell tool call. + The item type. Always `tool_search_call`. - - `type: "local_shell_call_output"` + - `"tool_search_call"` - The type of the local shell tool call output. Always `local_shell_call_output`. + - `id: optional string` - - `"local_shell_call_output"` + The unique ID of this tool search call. - `agent: optional object { agent_name }` @@ -202972,1242 +203900,1236 @@ Returns a list of input items for a given response. The canonical name of the agent that produced this item. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `call_id: optional string` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The unique ID of the tool search call generated by the model. - - `"in_progress"` + - `execution: optional "server" or "client"` - - `"completed"` + Whether tool search was executed by the server or by the client. - - `"incomplete"` + - `"server"` - - `ShellCall object { id, action, call_id, 6 more }` + - `"client"` - A tool call that executes one or more shell commands in a managed environment. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `id: string` + The status of the tool search call. - The unique ID of the shell tool call. Populated when this item is returned via API. + - `"in_progress"` - - `action: object { commands, max_output_length, timeout_ms }` + - `"completed"` - The shell commands and limits that describe how to run the tool call. + - `"incomplete"` - - `commands: array of string` + - `ToolSearchOutput object { tools, type, id, 4 more }` - - `max_output_length: number` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - Optional maximum number of characters to return from each command. + The loaded tool definitions returned by the tool search output. - - `timeout_ms: number` + - `Function object { name, parameters, strict, 5 more }` - Optional timeout in milliseconds for the commands. + 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). - - `call_id: string` + - `name: string` - The unique ID of the shell tool call generated by the model. + The name of the function to call. - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + - `parameters: map[unknown]` - Represents the use of a local environment to perform shell actions. + A JSON schema object describing the parameters of the function. - - `BetaResponseLocalEnvironment object { type }` + - `strict: boolean` - Represents the use of a local environment to perform shell actions. + Whether strict parameter validation is enforced for this function tool. - - `type: "local"` + - `type: "function"` - The environment type. Always `local`. + The type of the function tool. Always `function`. - - `"local"` + - `"function"` - - `BetaResponseContainerReference object { container_id, type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - Represents a container created with /v1/containers. + The tool invocation context(s). - - `container_id: string` + - `"direct"` - - `type: "container_reference"` + - `"programmatic"` - The environment type. Always `container_reference`. + - `defer_loading: optional boolean` - - `"container_reference"` + Whether this function is deferred and loaded via tool search. - - `status: "in_progress" or "completed" or "incomplete"` + - `description: optional string` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + A description of the function. Used by the model to determine whether or not to call the function. - - `"in_progress"` + - `output_schema: optional map[unknown]` - - `"completed"` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `"incomplete"` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `type: "shell_call"` + 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 `shell_call`. + - `type: "file_search"` - - `"shell_call"` + The type of the file search tool. Always `file_search`. - - `agent: optional object { agent_name }` + - `"file_search"` - The agent that produced this item. + - `vector_store_ids: array of string` - - `agent_name: string` + The IDs of the vector stores to search. - The canonical name of the agent that produced this item. + - `filters: optional object { key, type, value } or object { filters, type }` - - `caller: optional object { type } or object { caller_id, type }` + A filter to apply. - The execution context that produced this tool call. + - `ComparisonFilter object { key, type, value }` - - `Direct object { type }` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `type: "direct"` + - `key: string` - - `"direct"` + The key to compare against the value. - - `Program object { caller_id, type }` + - `type: "eq" or "ne" or "gt" or 5 more` - - `caller_id: string` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The call ID of the program item that produced this 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 - - `type: "program"` + - `"eq"` - - `"program"` + - `"ne"` - - `created_by: optional string` + - `"gt"` - The ID of the entity that created this tool call. + - `"gte"` - - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` + - `"lt"` - The output of a shell tool call that was emitted. + - `"lte"` - - `id: string` + - `"in"` - The unique ID of the shell call output. Populated when this item is returned via API. + - `"nin"` - - `call_id: string` + - `value: string or number or boolean or array of string or number` - The unique ID of the shell tool call generated by the model. + The value to compare against the attribute key; supports string, number, or boolean types. - - `max_output_length: number` + - `string` - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `number` - - `output: array of object { outcome, stderr, stdout, created_by }` + - `boolean` - An array of shell call output contents + - `array of string or number` - - `outcome: object { type } or object { exit_code, type }` + - `string` - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `number` - - `Timeout object { type }` + - `CompoundFilter object { filters, type }` - Indicates that the shell call exceeded its configured time limit. + Combine multiple filters using `and` or `or`. - - `type: "timeout"` + - `filters: array of object { key, type, value } or unknown` - The outcome type. Always `timeout`. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `"timeout"` + - `ComparisonFilter object { key, type, value }` - - `Exit object { exit_code, type }` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - Indicates that the shell commands finished and returned an exit code. + - `key: string` - - `exit_code: number` + The key to compare against the value. - Exit code from the shell process. + - `type: "eq" or "ne" or "gt" or 5 more` - - `type: "exit"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The outcome type. Always `exit`. + - `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 - - `"exit"` + - `"eq"` - - `stderr: string` + - `"ne"` - The standard error output that was captured. + - `"gt"` - - `stdout: string` + - `"gte"` - The standard output that was captured. + - `"lt"` - - `created_by: optional string` + - `"lte"` - The identifier of the actor that created the item. + - `"in"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"nin"` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `value: string or number or boolean or array of string or number` - - `"in_progress"` + The value to compare against the attribute key; supports string, number, or boolean types. - - `"completed"` + - `string` - - `"incomplete"` + - `number` - - `type: "shell_call_output"` + - `boolean` - The type of the shell call output. Always `shell_call_output`. + - `array of string or number` - - `"shell_call_output"` + - `string` - - `agent: optional object { agent_name }` + - `number` - The agent that produced this item. + - `unknown` - - `agent_name: string` + - `type: "and" or "or"` - The canonical name of the agent that produced this item. + Type of operation: `and` or `or`. - - `caller: optional object { type } or object { caller_id, type }` + - `"and"` - The execution context that produced this tool call. + - `"or"` - - `Direct object { type }` + - `max_num_results: optional number` - - `type: "direct"` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `"direct"` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `Program object { caller_id, type }` + Ranking options for search. - - `caller_id: string` + - `hybrid_search: optional object { embedding_weight, text_weight }` - The call ID of the program item that produced this tool call. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `type: "program"` + - `embedding_weight: number` - - `"program"` + The weight of the embedding in the reciprocal ranking fusion. - - `created_by: optional string` + - `text_weight: number` - The identifier of the actor that created the item. + The weight of the text in the reciprocal ranking fusion. - - `ApplyPatchCall object { id, call_id, operation, 5 more }` + - `ranker: optional "auto" or "default-2024-11-15"` - A tool call that applies file diffs by creating, deleting, or updating files. + The ranker to use for the file search. - - `id: string` + - `"auto"` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `"default-2024-11-15"` - - `call_id: string` + - `score_threshold: optional number` - The unique ID of the apply patch tool call generated by the model. + 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. - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `Computer object { type }` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `CreateFile object { diff, path, type }` + - `type: "computer"` - Instruction describing how to create a file via the apply_patch tool. + The type of the computer tool. Always `computer`. - - `diff: string` + - `"computer"` - Diff to apply. + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `path: string` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Path of the file to create. + - `display_height: number` - - `type: "create_file"` + The height of the computer display. - Create a new file with the provided diff. + - `display_width: number` - - `"create_file"` + The width of the computer display. - - `DeleteFile object { path, type }` + - `environment: "windows" or "mac" or "linux" or 2 more` - Instruction describing how to delete a file via the apply_patch tool. + The type of computer environment to control. - - `path: string` + - `"windows"` - Path of the file to delete. + - `"mac"` - - `type: "delete_file"` + - `"linux"` - Delete the specified file. + - `"ubuntu"` - - `"delete_file"` + - `"browser"` - - `UpdateFile object { diff, path, type }` + - `type: "computer_use_preview"` - Instruction describing how to update a file via the apply_patch tool. + The type of the computer use tool. Always `computer_use_preview`. - - `diff: string` + - `"computer_use_preview"` - Diff to apply. + - `WebSearch object { type, filters, search_context_size, user_location }` - - `path: string` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - Path of the file to update. + - `type: "web_search" or "web_search_2025_08_26"` - - `type: "update_file"` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - Update an existing file with the provided diff. + - `"web_search"` - - `"update_file"` + - `"web_search_2025_08_26"` - - `status: "in_progress" or "completed"` + - `filters: optional object { allowed_domains }` - The status of the apply patch tool call. One of `in_progress` or `completed`. + Filters for the search. - - `"in_progress"` + - `allowed_domains: optional array of string` - - `"completed"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `type: "apply_patch_call"` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - The type of the item. Always `apply_patch_call`. + - `search_context_size: optional "low" or "medium" or "high"` - - `"apply_patch_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. - - `agent: optional object { agent_name }` + - `"low"` - The agent that produced this item. + - `"medium"` - - `agent_name: string` + - `"high"` - The canonical name of the agent that produced this item. + - `user_location: optional object { city, country, region, 2 more }` - - `caller: optional object { type } or object { caller_id, type }` + The approximate location of the user. - The execution context that produced this tool call. + - `city: optional string` - - `Direct object { type }` + Free text input for the city of the user, e.g. `San Francisco`. - - `type: "direct"` + - `country: optional string` - - `"direct"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `Program object { caller_id, type }` + - `region: optional string` - - `caller_id: string` + Free text input for the region of the user, e.g. `California`. - The call ID of the program item that produced this tool call. + - `timezone: optional string` - - `type: "program"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"program"` + - `type: optional "approximate"` - - `created_by: optional string` + The type of location approximation. Always `approximate`. - The ID of the entity that created this tool call. + - `"approximate"` - - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - The output emitted by an apply patch 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 apply patch tool call output. Populated when this item is returned via API. + A label for this MCP server, used to identify it in tool calls. - - `call_id: string` + - `type: "mcp"` - The unique ID of the apply patch tool call generated by the model. + The type of the MCP tool. Always `mcp`. - - `status: "completed" or "failed"` + - `"mcp"` - The status of the apply patch tool call output. One of `completed` or `failed`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"completed"` + The tool invocation context(s). - - `"failed"` + - `"direct"` - - `type: "apply_patch_call_output"` + - `"programmatic"` - The type of the item. Always `apply_patch_call_output`. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `"apply_patch_call_output"` + List of allowed tool names or a filter object. - - `agent: optional object { agent_name }` + - `McpAllowedTools = array of string` - The agent that produced this item. + A string array of allowed tool names - - `agent_name: string` + - `McpToolFilter object { read_only, tool_names }` - The canonical name of the agent that produced this item. + 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. - - `"direct"` + - `authorization: optional string` - - `Program object { caller_id, type }` + 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_id: string` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - The call ID of the program item 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). - - `type: "program"` + Currently supported `connector_id` values are: - - `"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` - - `created_by: optional string` + - `"connector_dropbox"` - The ID of the entity that created this tool call output. + - `"connector_gmail"` - - `output: optional string` + - `"connector_googlecalendar"` - Optional textual output returned by the apply patch tool. + - `"connector_googledrive"` - - `McpListTools object { id, server_label, tools, 3 more }` + - `"connector_microsoftteams"` - A list of tools available on an MCP server. + - `"connector_outlookcalendar"` - - `id: string` + - `"connector_outlookemail"` - The unique ID of the list. + - `"connector_sharepoint"` - - `server_label: string` + - `defer_loading: optional boolean` - The label of the MCP server. + Whether this MCP tool is deferred and discovered via tool search. - - `tools: array of object { input_schema, name, annotations, description }` + - `headers: optional map[string]` - The tools available on the server. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `input_schema: unknown` + - `require_approval: optional object { always, never } or "always" or "never"` - The JSON schema describing the tool's input. + Specify which of the MCP server's tools require approval. - - `name: string` + - `McpToolApprovalFilter object { always, never }` - The name of the tool. + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - - `annotations: optional unknown` + - `always: optional object { read_only, tool_names }` - Additional annotations about the tool. + A filter object to specify which tools are allowed. - - `description: optional string` + - `read_only: optional boolean` - The description of the 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. - - `type: "mcp_list_tools"` + - `tool_names: optional array of string` - The type of the item. Always `mcp_list_tools`. + List of allowed tool names. - - `"mcp_list_tools"` + - `never: optional object { read_only, tool_names }` - - `agent: optional object { agent_name }` + A filter object to specify which tools are allowed. - The agent that produced this item. + - `read_only: optional boolean` - - `agent_name: string` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The canonical name of the agent that produced this item. + - `tool_names: optional array of string` - - `error: optional string` + List of allowed tool names. - Error message if the server could not list tools. + - `McpToolApprovalSetting = "always" or "never"` - - `McpApprovalRequest object { id, arguments, name, 3 more }` + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - A request for human approval of a tool invocation. + - `"always"` - - `id: string` + - `"never"` - The unique ID of the approval request. + - `server_description: optional string` - - `arguments: string` + Optional description of the MCP server, used to provide more context. - A JSON string of arguments for the tool. + - `server_url: optional string` - - `name: string` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - The name of the tool to run. + - `tunnel_id: optional string` - - `server_label: string` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - The label of the MCP server making the request. + - `CodeInterpreter object { container, type, allowed_callers }` - - `type: "mcp_approval_request"` + A tool that runs Python code to help generate a response to a prompt. - The type of the item. Always `mcp_approval_request`. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `"mcp_approval_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. - - `agent: optional object { agent_name }` + - `string` - The agent that produced this item. + The container ID. - - `agent_name: string` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - The canonical name of the agent that produced this item. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` + - `type: "auto"` - A response to an MCP approval request. + Always `auto`. - - `id: string` + - `"auto"` - The unique ID of the approval response + - `file_ids: optional array of string` - - `approval_request_id: string` + An optional list of uploaded files to make available to your code. - The ID of the approval request being answered. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `approve: boolean` + The memory limit for the code interpreter container. - Whether the request was approved. + - `"1g"` - - `type: "mcp_approval_response"` + - `"4g"` - The type of the item. Always `mcp_approval_response`. + - `"16g"` - - `"mcp_approval_response"` + - `"64g"` - - `agent: optional object { agent_name }` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - The agent that produced this item. + Network access policy for the container. - - `agent_name: string` + - `BetaContainerNetworkPolicyDisabled object { type }` - The canonical name of the agent that produced this item. + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `reason: optional string` + - `type: "code_interpreter"` - Optional reason for the decision. + The type of the code interpreter tool. Always `code_interpreter`. - - `McpCall object { id, arguments, name, 7 more }` + - `"code_interpreter"` - 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. + - `ProgrammaticToolCalling object { type }` - - `name: string` + - `type: "programmatic_tool_calling"` - The name of the tool that was run. + The type of the tool. Always `programmatic_tool_calling`. - - `server_label: string` + - `"programmatic_tool_calling"` - The label of the MCP server running the tool. + - `ImageGeneration object { type, action, background, 9 more }` - - `type: "mcp_call"` + A tool that generates images using the GPT image models. - The type of the item. Always `mcp_call`. + - `type: "image_generation"` - - `"mcp_call"` + The type of the image generation tool. Always `image_generation`. - - `agent: optional object { agent_name }` + - `"image_generation"` - The agent that produced this item. + - `action: optional "generate" or "edit" or "auto"` - - `agent_name: string` + Whether to generate a new image or edit an existing image. Default: `auto`. - The canonical name of the agent that produced this item. + - `"generate"` - - `approval_request_id: optional string` + - `"edit"` - 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. + - `"auto"` - - `error: optional string` + - `background: optional "transparent" or "opaque" or "auto"` - The error from the tool call, if any. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `output: optional string` + - `"transparent"` - The output from the tool call. + - `"opaque"` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `"auto"` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `input_fidelity: optional "high" or "low"` - - `"in_progress"` + 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`. - - `"completed"` + - `"high"` - - `"incomplete"` + - `"low"` - - `"calling"` + - `input_image_mask: optional object { file_id, image_url }` - - `"failed"` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `CustomToolCall object { id, call_id, input, 7 more }` + - `file_id: optional string` - - `id: string` + File ID for the mask image. - The unique ID of the custom tool call item. + - `image_url: optional string` - - `call_id: string` + Base64-encoded mask image. - An identifier used to map this custom tool call to a tool call output. + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `input: string` + The image generation model to use. Default: `gpt-image-1`. - The input for the custom tool call generated by the model. + - `string` - - `name: string` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The name of the custom tool being called. + The image generation model to use. Default: `gpt-image-1`. - - `status: "in_progress" or "completed" or "incomplete"` + - `"gpt-image-1"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"gpt-image-1-mini"` - - `"in_progress"` + - `"gpt-image-1.5"` - - `"completed"` + - `moderation: optional "auto" or "low"` - - `"incomplete"` + Moderation level for the generated image. Default: `auto`. - - `type: "custom_tool_call"` + - `"auto"` - The type of the custom tool call. Always `custom_tool_call`. + - `"low"` - - `"custom_tool_call"` + - `output_compression: optional number` - - `agent: optional object { agent_name }` + Compression level for the output image. Default: 100. - The agent that produced this item. + - `output_format: optional "png" or "webp" or "jpeg"` - - `agent_name: string` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The canonical name of the agent that produced this item. + - `"png"` - - `caller: optional object { type } or object { caller_id, type }` + - `"webp"` - The execution context that produced this tool call. + - `"jpeg"` - - `Direct object { type }` + - `partial_images: optional number` - - `type: "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"` - - `"program"` + - `"auto"` - - `created_by: optional string` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - The identifier of the actor that created the item. + 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`. - - `namespace: optional string` + - `string` - The namespace of the custom tool being called. + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `CustomToolCallOutput object { id, call_id, output, 5 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`. - - `id: string` + - `"1024x1024"` - The unique ID of the custom tool call output item. + - `"1024x1536"` - - `call_id: string` + - `"1536x1024"` - The call ID, used to map this custom tool call output to a custom tool call. + - `"auto"` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `LocalShell object { type }` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + A tool that allows the model to execute shell commands in a local environment. - - `StringOutput = string` + - `type: "local_shell"` - A string of the output of the custom tool call. + The type of the local shell tool. Always `local_shell`. - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `"local_shell"` - Text, image, or file output of the custom tool call. + - `Shell object { type, allowed_callers, environment }` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + A tool that allows the model to execute shell commands. - A text input to the model. + - `type: "shell"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + The type of the shell tool. Always `shell`. - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `"shell"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `allowed_callers: optional array of "direct" or "programmatic"` - A file input to the model. + The tool invocation context(s). - - `status: "in_progress" or "completed" or "incomplete"` + - `"direct"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"programmatic"` - - `"in_progress"` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `"completed"` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `"incomplete"` + - `BetaLocalEnvironment object { type, skills }` - - `type: "custom_tool_call_output"` + - `BetaContainerReference object { container_id, type }` - The type of the custom tool call output. Always `custom_tool_call_output`. + - `Custom object { name, type, allowed_callers, 3 more }` - - `"custom_tool_call_output"` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `agent: optional object { agent_name }` + - `name: string` - The agent that produced this item. + The name of the custom tool, used to identify it in tool calls. - - `agent_name: string` + - `type: "custom"` - The canonical name of the agent that produced this item. + The type of the custom tool. Always `custom`. - - `caller: optional object { type } or object { caller_id, type }` + - `"custom"` - The execution context that produced this tool call. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `Direct object { type }` + The tool invocation context(s). - - `type: "direct"` + - `"direct"` - The caller type. Always `direct`. + - `"programmatic"` - - `"direct"` + - `defer_loading: optional boolean` - - `Program object { caller_id, type }` + Whether this tool should be deferred and discovered via tool search. - - `caller_id: string` + - `description: optional string` - The call ID of the program item that produced this tool call. + Optional description of the custom tool, used to provide more context. - - `type: "program"` + - `format: optional object { type } or object { definition, syntax, type }` - The caller type. Always `program`. + The input format for the custom tool. Default is unconstrained text. - - `"program"` + - `Text object { type }` - - `created_by: optional string` + Unconstrained free-form text. - The identifier of the actor that created the item. + - `type: "text"` - - `first_id: string` + Unconstrained text format. Always `text`. - The ID of the first item in the list. + - `"text"` - - `has_more: boolean` + - `Grammar object { definition, syntax, type }` - Whether there are more items available. + A grammar defined by the user. - - `last_id: string` + - `definition: string` - The ID of the last item in the list. + The grammar definition. - - `object: "list"` + - `syntax: "lark" or "regex"` - The type of object returned, must be `list`. + The syntax of the grammar definition. One of `lark` or `regex`. - - `"list"` + - `"lark"` -### Example + - `"regex"` -```http -curl https://api.openai.com/v1/responses/$RESPONSE_ID/input_items \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `type: "grammar"` -#### Response + Grammar format. Always `grammar`. -```json -{ - "data": [ - { - "id": "id", - "content": [ - { - "text": "text", - "type": "input_text", - "prompt_cache_breakpoint": { - "mode": "explicit" - } - } - ], - "role": "user", - "type": "message", - "agent": { - "agent_name": "agent_name" - }, - "status": "in_progress" - } - ], - "first_id": "first_id", - "has_more": true, - "last_id": "last_id", - "object": "list" -} -``` + - `"grammar"` + + - `Namespace object { description, name, tools, type }` -### Example + Groups function/custom tools under a shared namespace. -```http -curl https://api.openai.com/v1/responses/resp_abc123/input_items \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `description: string` -#### Response + A description of the namespace shown to the model. -```json -{ - "object": "list", - "data": [ - { - "id": "msg_abc123", - "type": "message", - "role": "user", - "content": [ - { - "type": "input_text", - "text": "Tell me a three sentence bedtime story about a unicorn." - } - ] - } - ], - "first_id": "msg_abc123", - "last_id": "msg_abc123", - "has_more": false -} -``` + - `name: string` -## Domain Types + The namespace name used in tool calls (for example, `crm`). -### Beta Response Item List + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` -- `BetaResponseItemList object { data, first_id, has_more, 2 more }` + The function/custom tools available inside this namespace. - A list of Response items. + - `Function object { name, type, allowed_callers, 5 more }` - - `data: array of BetaResponseInputMessageItem or BetaResponseOutputMessage or object { id, queries, status, 3 more } or 29 more` + - `name: string` - A list of items used to generate this response. + - `type: "function"` - - `BetaResponseInputMessageItem object { id, content, role, 3 more }` + - `"function"` - - `id: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The unique ID of the message input. + The tool invocation context(s). - - `content: BetaResponseInputMessageContentList` + - `"direct"` - A list of one or many input items to the model, containing different content - types. + - `"programmatic"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `defer_loading: optional boolean` - A text input to the model. + Whether this function should be deferred and discovered via tool search. - - `text: string` + - `description: optional string` - The text input to the model. + - `output_schema: optional map[unknown]` - - `type: "input_text"` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - The type of the input item. Always `input_text`. + - `parameters: optional unknown` - - `"input_text"` + - `strict: optional boolean` - - `prompt_cache_breakpoint: optional object { mode }` + 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. - 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. + - `Custom object { name, type, allowed_callers, 3 more }` - - `mode: "explicit"` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - The breakpoint mode. Always `explicit`. + - `name: string` - - `"explicit"` + The name of the custom tool, used to identify it in tool calls. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `type: "custom"` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + The type of the custom tool. Always `custom`. - - `detail: "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` - - `type: "input_image"` + Whether this tool should be deferred and discovered via tool search. - The type of the input item. Always `input_image`. + - `description: optional string` - - `"input_image"` + Optional description of the custom tool, used to provide more context. - - `file_id: optional string` + - `format: optional object { type } or object { definition, syntax, type }` - The ID of the file to be sent to the model. + The input format for the custom tool. Default is unconstrained text. - - `image_url: optional string` + - `Text object { type }` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + Unconstrained free-form text. - - `prompt_cache_breakpoint: optional object { mode }` + - `type: "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. + Unconstrained text format. Always `text`. - - `mode: "explicit"` + - `"text"` - The breakpoint mode. Always `explicit`. + - `Grammar object { definition, syntax, type }` - - `"explicit"` + A grammar defined by the user. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `definition: string` - A file input to the model. + The grammar definition. - - `type: "input_file"` + - `syntax: "lark" or "regex"` - The type of the input item. Always `input_file`. + The syntax of the grammar definition. One of `lark` or `regex`. - - `"input_file"` + - `"lark"` - - `detail: optional "auto" or "low" or "high"` + - `"regex"` - 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: "grammar"` - - `"auto"` + Grammar format. Always `grammar`. - - `"low"` + - `"grammar"` - - `"high"` + - `type: "namespace"` - - `file_data: optional string` + The type of the tool. Always `namespace`. - The content of the file to be sent to the model. + - `"namespace"` - - `file_id: optional string` + - `ToolSearch object { type, description, execution, parameters }` - The ID of the file to be sent to the model. + Hosted or BYOT tool search configuration for deferred tools. - - `file_url: optional string` + - `type: "tool_search"` - The URL of the file to be sent to the model. + The type of the tool. Always `tool_search`. - - `filename: optional string` + - `"tool_search"` - The name of the file to be sent to the model. + - `description: optional string` - - `prompt_cache_breakpoint: optional object { mode }` + Description shown to the model for a client-executed tool search tool. - 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. + - `execution: optional "server" or "client"` - - `mode: "explicit"` + Whether tool search is executed by the server or by the client. - The breakpoint mode. Always `explicit`. + - `"server"` - - `"explicit"` + - `"client"` - - `role: "user" or "system" or "developer"` + - `parameters: optional unknown` - The role of the message input. One of `user`, `system`, or `developer`. + Parameter schema for a client-executed tool search tool. - - `"user"` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `"system"` + 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). - - `"developer"` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `type: "message"` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The type of the message input. Always set to `message`. + - `"web_search_preview"` - - `"message"` + - `"web_search_preview_2025_03_11"` - - `agent: optional object { agent_name }` + - `search_content_types: optional array of "text" or "image"` - The agent that produced this item. + - `"text"` - - `agent_name: string` + - `"image"` - The canonical name of the agent that produced this item. + - `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 item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"low"` - - `"in_progress"` + - `"medium"` - - `"completed"` + - `"high"` - - `"incomplete"` + - `user_location: optional object { type, city, country, 2 more }` - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + The user's location. - An output message from the model. + - `type: "approximate"` - - `id: string` + The type of location approximation. Always `approximate`. - The unique ID of the output message. + - `"approximate"` - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + - `city: optional string` - The content of the output message. + Free text input for the city of the user, e.g. `San Francisco`. - - `BetaResponseOutputText object { annotations, logprobs, text, type }` + - `country: optional string` - A text output from the model. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `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 }` + - `region: optional string` - The annotations of the text output. + Free text input for the region of the user, e.g. `California`. - - `FileCitation object { file_id, filename, index, type }` + - `timezone: optional string` - A citation to a file. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `file_id: string` + - `ApplyPatch object { type, allowed_callers }` - The ID of the file. + Allows the assistant to create, delete, or update files using unified diffs. - - `filename: string` + - `type: "apply_patch"` - The filename of the file cited. + The type of the tool. Always `apply_patch`. - - `index: number` + - `"apply_patch"` - The index of the file in the list of files. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "file_citation"` + The tool invocation context(s). - The type of the file citation. Always `file_citation`. + - `"direct"` - - `"file_citation"` + - `"programmatic"` - - `URLCitation object { end_index, start_index, title, 2 more }` + - `type: "tool_search_output"` - A citation for a web resource used to generate a model response. + The item type. Always `tool_search_output`. - - `end_index: number` + - `"tool_search_output"` - The index of the last character of the URL citation in the message. + - `id: optional string` - - `start_index: number` + The unique ID of this tool search output. - The index of the first character of the URL citation in the message. + - `agent: optional object { agent_name }` - - `title: string` + The agent that produced this item. - The title of the web resource. + - `agent_name: string` - - `type: "url_citation"` + The canonical name of the agent that produced this item. - The type of the URL citation. Always `url_citation`. + - `call_id: optional string` - - `"url_citation"` + The unique ID of the tool search call generated by the model. - - `url: string` + - `execution: optional "server" or "client"` - The URL of the web resource. + Whether tool search was executed by the server or by the client. - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + - `"server"` - A citation for a container file used to generate a model response. + - `"client"` - - `container_id: string` + - `status: optional "in_progress" or "completed" or "incomplete"` - The ID of the container file. + The status of the tool search output. - - `end_index: number` + - `"in_progress"` - The index of the last character of the container file citation in the message. + - `"completed"` - - `file_id: string` + - `"incomplete"` - The ID of the file. + - `AdditionalTools object { role, tools, type, 2 more }` - - `filename: string` + - `role: "developer"` - The filename of the container file cited. + The role that provided the additional tools. Only `developer` is supported. - - `start_index: number` + - `"developer"` - The index of the first character of the container file citation in the 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` - - `type: "container_file_citation"` + A list of additional tools made available at this item. - The type of the container file citation. Always `container_file_citation`. + - `Function object { name, parameters, strict, 5 more }` - - `"container_file_citation"` + 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). - - `FilePath object { file_id, index, type }` + - `name: string` - A path to a file. + The name of the function to call. - - `file_id: string` + - `parameters: map[unknown]` - The ID of the file. + A JSON schema object describing the parameters of the function. - - `index: number` + - `strict: boolean` - The index of the file in the list of files. + Whether strict parameter validation is enforced for this function tool. - - `type: "file_path"` + - `type: "function"` - The type of the file path. Always `file_path`. + The type of the function tool. Always `function`. - - `"file_path"` + - `"function"` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `token: string` + The tool invocation context(s). - - `bytes: array of number` + - `"direct"` - - `logprob: number` + - `"programmatic"` - - `top_logprobs: array of object { token, bytes, logprob }` + - `defer_loading: optional boolean` - - `token: string` + Whether this function is deferred and loaded via tool search. - - `bytes: array of number` + - `description: optional string` - - `logprob: number` + A description of the function. Used by the model to determine whether or not to call the function. - - `text: string` + - `output_schema: optional map[unknown]` - The text output from the model. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `type: "output_text"` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - The type of the output text. Always `output_text`. + 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). - - `"output_text"` + - `type: "file_search"` - - `BetaResponseOutputRefusal object { refusal, type }` + The type of the file search tool. Always `file_search`. - A refusal from the model. + - `"file_search"` - - `refusal: string` + - `vector_store_ids: array of string` - The refusal explanation from the model. + The IDs of the vector stores to search. - - `type: "refusal"` + - `filters: optional object { key, type, value } or object { filters, type }` - The type of the refusal. Always `refusal`. + A filter to apply. - - `"refusal"` + - `ComparisonFilter object { key, type, value }` - - `role: "assistant"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The role of the output message. Always `assistant`. + - `key: string` - - `"assistant"` + The key to compare against the value. - - `status: "in_progress" or "completed" or "incomplete"` + - `type: "eq" or "ne" or "gt" or 5 more` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"in_progress"` + - `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 - - `"completed"` + - `"eq"` - - `"incomplete"` + - `"ne"` - - `type: "message"` + - `"gt"` - The type of the output message. Always `message`. + - `"gte"` - - `"message"` + - `"lt"` - - `agent: optional object { agent_name }` + - `"lte"` - The agent that produced this item. + - `"in"` - - `agent_name: string` + - `"nin"` - The canonical name of the agent that produced this item. + - `value: string or number or boolean or array of string or number` - - `phase: optional "commentary" or "final_answer"` + The value to compare against the attribute key; supports string, number, or boolean types. - 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. + - `string` - - `"commentary"` + - `number` - - `"final_answer"` + - `boolean` - - `FileSearchCall object { id, queries, status, 3 more }` + - `array of string or number` - The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + - `string` - - `id: string` + - `number` - The unique ID of the file search tool call. + - `CompoundFilter object { filters, type }` - - `queries: array of string` + Combine multiple filters using `and` or `or`. - The queries used to search for files. + - `filters: array of object { key, type, value } or unknown` - - `status: "in_progress" or "searching" or "completed" or 2 more` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `ComparisonFilter object { key, type, value }` - - `"in_progress"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"searching"` + - `key: string` - - `"completed"` + The key to compare against the value. - - `"incomplete"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `"failed"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `type: "file_search_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 - The type of the file search tool call. Always `file_search_call`. + - `"eq"` - - `"file_search_call"` + - `"ne"` - - `agent: optional object { agent_name }` + - `"gt"` - The agent that produced this item. + - `"gte"` - - `agent_name: string` + - `"lt"` - The canonical name of the agent that produced this item. + - `"lte"` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + - `"in"` - The results of the file search tool call. + - `"nin"` - - `attributes: optional map[string or number or boolean]` + - `value: string or number or boolean or array of string or number` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + The value to compare against the attribute key; supports string, number, or boolean types. - `string` @@ -204215,787 +205137,836 @@ curl https://api.openai.com/v1/responses/resp_abc123/input_items \ - `boolean` - - `file_id: optional string` + - `array of string or number` - The unique ID of the file. + - `string` - - `filename: optional string` + - `number` - The name of the file. + - `unknown` - - `score: optional number` + - `type: "and" or "or"` - The relevance score of the file - a value between 0 and 1. + Type of operation: `and` or `or`. - - `text: optional string` + - `"and"` - The text that was retrieved from the file. + - `"or"` - - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` + - `max_num_results: optional number` - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `id: string` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - The unique ID of the computer call. + Ranking options for search. - - `call_id: string` + - `hybrid_search: optional object { embedding_weight, text_weight }` - An identifier used when responding to the tool call with output. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `pending_safety_checks: array of object { id, code, message }` + - `embedding_weight: number` - The pending safety checks for the computer call. + The weight of the embedding in the reciprocal ranking fusion. - - `id: string` + - `text_weight: number` - The ID of the pending safety check. + The weight of the text in the reciprocal ranking fusion. - - `code: optional string` + - `ranker: optional "auto" or "default-2024-11-15"` - The type of the pending safety check. + The ranker to use for the file search. - - `message: optional string` + - `"auto"` - Details about the pending safety check. + - `"default-2024-11-15"` - - `status: "in_progress" or "completed" or "incomplete"` + - `score_threshold: optional number` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + 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. - - `"in_progress"` + - `Computer object { type }` - - `"completed"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"incomplete"` + - `type: "computer"` - - `type: "computer_call"` + The type of the computer tool. Always `computer`. - The type of the computer call. Always `computer_call`. + - `"computer"` - - `"computer_call"` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `action: optional BetaComputerAction` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - A click action. + - `display_height: number` - - `Click object { button, type, x, 2 more }` + The height of the computer display. - A click action. + - `display_width: number` - - `button: "left" or "right" or "wheel" or 2 more` + The width of the computer display. - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `environment: "windows" or "mac" or "linux" or 2 more` - - `"left"` + The type of computer environment to control. - - `"right"` + - `"windows"` - - `"wheel"` + - `"mac"` - - `"back"` + - `"linux"` - - `"forward"` + - `"ubuntu"` - - `type: "click"` + - `"browser"` - Specifies the event type. For a click action, this property is always `click`. + - `type: "computer_use_preview"` - - `"click"` + The type of the computer use tool. Always `computer_use_preview`. - - `x: number` + - `"computer_use_preview"` - The x-coordinate where the click occurred. + - `WebSearch object { type, filters, search_context_size, user_location }` - - `y: number` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - The y-coordinate where the click occurred. + - `type: "web_search" or "web_search_2025_08_26"` - - `keys: optional array of string` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - The keys being held while clicking. + - `"web_search"` - - `DoubleClick object { keys, type, x, y }` + - `"web_search_2025_08_26"` - A double click action. + - `filters: optional object { allowed_domains }` - - `keys: array of string` + Filters for the search. - The keys being held while double-clicking. + - `allowed_domains: optional array of string` - - `type: "double_click"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - Specifies the event type. For a double click action, this property is always set to `double_click`. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `"double_click"` + - `search_context_size: optional "low" or "medium" or "high"` - - `x: number` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - The x-coordinate where the double click occurred. + - `"low"` - - `y: number` + - `"medium"` - The y-coordinate where the double click occurred. + - `"high"` - - `Drag object { path, type, keys }` + - `user_location: optional object { city, country, region, 2 more }` - A drag action. + The approximate location of the user. - - `path: array of object { x, y }` + - `city: optional string` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + Free text input for the city of the user, e.g. `San Francisco`. - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `country: optional string` - - `x: number` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The x-coordinate. + - `region: optional string` - - `y: number` + Free text input for the region of the user, e.g. `California`. - The y-coordinate. + - `timezone: optional string` - - `type: "drag"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - Specifies the event type. For a drag action, this property is always set to `drag`. + - `type: optional "approximate"` - - `"drag"` + The type of location approximation. Always `approximate`. - - `keys: optional array of string` + - `"approximate"` - The keys being held while dragging the mouse. + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `Keypress object { keys, type }` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - A collection of keypresses the model would like to perform. + - `server_label: string` - - `keys: array of string` + A label for this MCP server, used to identify it in tool calls. - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + - `type: "mcp"` - - `type: "keypress"` + The type of the MCP tool. Always `mcp`. - Specifies the event type. For a keypress action, this property is always set to `keypress`. + - `"mcp"` - - `"keypress"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `Move object { type, x, y, keys }` + The tool invocation context(s). - A mouse move action. + - `"direct"` - - `type: "move"` + - `"programmatic"` - Specifies the event type. For a move action, this property is always set to `move`. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `"move"` + List of allowed tool names or a filter object. - - `x: number` + - `McpAllowedTools = array of string` - The x-coordinate to move to. + A string array of allowed tool names - - `y: number` + - `McpToolFilter object { read_only, tool_names }` - The y-coordinate to move to. + A filter object to specify which tools are allowed. - - `keys: optional array of string` + - `read_only: optional boolean` - The keys being held while moving the mouse. + 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. - - `Screenshot object { type }` + - `tool_names: optional array of string` - A screenshot action. + List of allowed tool names. - - `type: "screenshot"` + - `authorization: optional string` - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + 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. - - `"screenshot"` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `Scroll object { scroll_x, scroll_y, type, 3 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 scroll action. + Currently supported `connector_id` values are: - - `scroll_x: number` + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - The horizontal scroll distance. + - `"connector_dropbox"` - - `scroll_y: number` + - `"connector_gmail"` - The vertical scroll distance. + - `"connector_googlecalendar"` - - `type: "scroll"` + - `"connector_googledrive"` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `"connector_microsoftteams"` - - `"scroll"` + - `"connector_outlookcalendar"` - - `x: number` + - `"connector_outlookemail"` - The x-coordinate where the scroll occurred. + - `"connector_sharepoint"` - - `y: number` + - `defer_loading: optional boolean` - The y-coordinate where the scroll occurred. + Whether this MCP tool is deferred and discovered via tool search. - - `keys: optional array of string` + - `headers: optional map[string]` - The keys being held while scrolling. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `Type object { text, type }` + - `require_approval: optional object { always, never } or "always" or "never"` - An action to type in text. + Specify which of the MCP server's tools require approval. - - `text: string` + - `McpToolApprovalFilter object { always, never }` - The text to 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. - - `type: "type"` + - `always: optional object { read_only, tool_names }` - Specifies the event type. For a type action, this property is always set to `type`. + A filter object to specify which tools are allowed. - - `"type"` + - `read_only: optional boolean` - - `Wait 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. - A wait action. + - `tool_names: optional array of string` - - `type: "wait"` + List of allowed tool names. - Specifies the event type. For a wait action, this property is always set to `wait`. + - `never: optional object { read_only, tool_names }` - - `"wait"` + A filter object to specify which tools are allowed. - - `actions: optional BetaComputerActionList` + - `read_only: optional boolean` - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + 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. - - `Click object { button, type, x, 2 more }` + - `tool_names: optional array of string` - A click action. + List of allowed tool names. - - `DoubleClick object { keys, type, x, y }` + - `McpToolApprovalSetting = "always" or "never"` - A double click action. + 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. - - `Drag object { path, type, keys }` + - `"always"` - A drag action. + - `"never"` - - `Keypress object { keys, type }` + - `server_description: optional string` - A collection of keypresses the model would like to perform. + Optional description of the MCP server, used to provide more context. - - `Move object { type, x, y, keys }` + - `server_url: optional string` - A mouse move action. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `Screenshot object { type }` + - `tunnel_id: optional string` - A screenshot 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. - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `CodeInterpreter object { container, type, allowed_callers }` - A scroll action. + A tool that runs Python code to help generate a response to a prompt. - - `Type object { text, type }` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - An action to type in text. + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - - `Wait object { type }` + - `string` - A wait action. + The container ID. - - `agent: optional object { agent_name }` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - The agent that produced this item. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `agent_name: string` + - `type: "auto"` - The canonical name of the agent that produced this item. + Always `auto`. - - `ComputerCallOutput object { id, call_id, output, 5 more }` + - `"auto"` - - `id: string` + - `file_ids: optional array of string` - The unique ID of the computer call tool output. + An optional list of uploaded files to make available to your code. - - `call_id: string` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The ID of the computer tool call that produced the output. + The memory limit for the code interpreter container. - - `output: BetaResponseComputerToolCallOutputScreenshot` + - `"1g"` - A computer screenshot image used with the computer use tool. + - `"4g"` - - `type: "computer_screenshot"` + - `"16g"` - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `"64g"` - - `"computer_screenshot"` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `file_id: optional string` + Network access policy for the container. - The identifier of an uploaded file that contains the screenshot. + - `BetaContainerNetworkPolicyDisabled object { type }` - - `image_url: optional string` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - The URL of the screenshot image. + - `type: "code_interpreter"` - - `status: "completed" or "incomplete" or "failed" or "in_progress"` + The type of the code interpreter tool. Always `code_interpreter`. - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `"code_interpreter"` - - `"completed"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"incomplete"` + The tool invocation context(s). - - `"failed"` + - `"direct"` - - `"in_progress"` + - `"programmatic"` - - `type: "computer_call_output"` + - `ProgrammaticToolCalling object { type }` - The type of the computer tool call output. Always `computer_call_output`. + - `type: "programmatic_tool_calling"` - - `"computer_call_output"` + The type of the tool. Always `programmatic_tool_calling`. - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `"programmatic_tool_calling"` - The safety checks reported by the API that have been acknowledged by the - developer. + - `ImageGeneration object { type, action, background, 9 more }` - - `id: string` + A tool that generates images using the GPT image models. - The ID of the pending safety check. + - `type: "image_generation"` - - `code: optional string` + The type of the image generation tool. Always `image_generation`. - The type of the pending safety check. + - `"image_generation"` - - `message: optional string` + - `action: optional "generate" or "edit" or "auto"` - Details about the pending safety check. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `agent: optional object { agent_name }` + - `"generate"` - The agent that produced this item. + - `"edit"` - - `agent_name: string` + - `"auto"` - The canonical name of the agent that produced this item. + - `background: optional "transparent" or "opaque" or "auto"` - - `created_by: optional string` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - The identifier of the actor that created the item. + - `"transparent"` - - `WebSearchCall object { id, action, status, 2 more }` + - `"opaque"` - The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + - `"auto"` - - `id: string` + - `input_fidelity: optional "high" or "low"` - The unique ID of the web search tool call. + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `"high"` - 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). + - `"low"` - - `Search object { type, queries, query, sources }` + - `input_image_mask: optional object { file_id, image_url }` - Action type "search" - Performs a web search query. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `type: "search"` + - `file_id: optional string` - The action type. + File ID for the mask image. - - `"search"` + - `image_url: optional string` - - `queries: optional array of string` + Base64-encoded mask image. - The search queries. + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `query: optional string` + The image generation model to use. Default: `gpt-image-1`. - The search query. + - `string` - - `sources: optional array of object { type, url }` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The sources used in the search. + The image generation model to use. Default: `gpt-image-1`. - - `type: "url"` + - `"gpt-image-1"` - The type of source. Always `url`. + - `"gpt-image-1-mini"` - - `"url"` + - `"gpt-image-1.5"` - - `url: string` + - `moderation: optional "auto" or "low"` - The URL of the source. + Moderation level for the generated image. Default: `auto`. - - `OpenPage object { type, url }` + - `"auto"` - Action type "open_page" - Opens a specific URL from search results. + - `"low"` - - `type: "open_page"` + - `output_compression: optional number` - The action type. + Compression level for the output image. Default: 100. - - `"open_page"` + - `output_format: optional "png" or "webp" or "jpeg"` - - `url: optional string` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The URL opened by the model. + - `"png"` - - `FindInPage object { pattern, type, url }` + - `"webp"` - Action type "find_in_page": Searches for a pattern within a loaded page. + - `"jpeg"` - - `pattern: string` + - `partial_images: optional number` - The pattern or text to search for within the page. + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `type: "find_in_page"` + - `quality: optional "low" or "medium" or "high" or "auto"` - The action type. + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `"find_in_page"` + - `"low"` - - `url: string` + - `"medium"` - The URL of the page searched for the pattern. + - `"high"` - - `status: "in_progress" or "searching" or "completed" or "failed"` + - `"auto"` - The status of the web search tool call. + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `"in_progress"` + 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`. - - `"searching"` + - `string` - - `"completed"` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `"failed"` + 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: "web_search_call"` + - `"1024x1024"` - The type of the web search tool call. Always `web_search_call`. + - `"1024x1536"` - - `"web_search_call"` + - `"1536x1024"` - - `agent: optional object { agent_name }` + - `"auto"` - The agent that produced this item. + - `LocalShell object { type }` - - `agent_name: string` + A tool that allows the model to execute shell commands in a local environment. - The canonical name of the agent that produced this item. + - `type: "local_shell"` - - `FunctionCall object { id, arguments, call_id, 7 more }` + The type of the local shell tool. Always `local_shell`. - - `id: string` + - `"local_shell"` - The unique ID of the function tool call. + - `Shell object { type, allowed_callers, environment }` - - `arguments: string` + 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 BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + + - `BetaLocalEnvironment object { type, skills }` + + - `BetaContainerReference 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"` - A JSON string of the arguments to pass to the function. + The type of the custom tool. Always `custom`. - - `call_id: string` + - `"custom"` - The unique ID of the function 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 function to run. + - `"direct"` - - `status: "in_progress" or "completed" or "incomplete"` + - `"programmatic"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `defer_loading: optional boolean` - - `"in_progress"` + Whether this tool should be deferred and discovered via tool search. - - `"completed"` + - `description: optional string` - - `"incomplete"` + Optional description of the custom tool, used to provide more context. - - `type: "function_call"` + - `format: optional object { type } or object { definition, syntax, type }` - The type of the function tool call. Always `function_call`. + The input format for the custom tool. Default is unconstrained text. - - `"function_call"` + - `Text object { type }` - - `agent: optional object { agent_name }` + Unconstrained free-form text. - The agent that produced this item. + - `type: "text"` - - `agent_name: string` + Unconstrained text format. Always `text`. - The canonical name of the agent that produced this item. + - `"text"` - - `caller: optional object { type } or object { caller_id, type }` + - `Grammar object { definition, syntax, type }` - The execution context that produced this tool call. + A grammar defined by the user. - - `Direct object { type }` + - `definition: string` - - `type: "direct"` + The grammar definition. - - `"direct"` + - `syntax: "lark" or "regex"` - - `Program object { caller_id, type }` + The syntax of the grammar definition. One of `lark` or `regex`. - - `caller_id: string` + - `"lark"` - The call ID of the program item that produced this tool call. + - `"regex"` - - `type: "program"` + - `type: "grammar"` - - `"program"` + Grammar format. Always `grammar`. - - `created_by: optional string` + - `"grammar"` - The identifier of the actor that created the item. + - `Namespace object { description, name, tools, type }` - - `namespace: optional string` + Groups function/custom tools under a shared namespace. - The namespace of the function to run. + - `description: string` - - `FunctionCallOutput object { id, call_id, output, 5 more }` + A description of the namespace shown to the model. - - `id: string` + - `name: string` - The unique ID of the function call tool output. + 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 function tool call generated by the model. + The function/custom tools available inside this namespace. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `Function object { name, type, allowed_callers, 5 more }` - The output from the function call generated by your code. - Can be a string or an list of output content. + - `name: string` - - `StringOutput = string` + - `type: "function"` - A string of the output of the function call. + - `"function"` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `allowed_callers: optional array of "direct" or "programmatic"` - Text, image, or file output of the function call. + The tool invocation context(s). - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `"direct"` - A text input to the model. + - `"programmatic"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `defer_loading: optional boolean` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + Whether this function should be deferred and discovered via tool search. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `description: optional string` - A file input to the model. + - `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 item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `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: "function_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 function tool call output. Always `function_call_output`. + - `name: string` - - `"function_call_output"` + The name of the custom tool, used to identify it in tool calls. - - `agent: optional object { agent_name }` + - `type: "custom"` - The agent that produced this item. + The type of the custom tool. Always `custom`. - - `agent_name: string` + - `"custom"` - The canonical name of the agent that produced this item. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `caller: optional object { type } or object { caller_id, type }` + The tool invocation context(s). - The execution context that produced this tool call. + - `"direct"` - - `Direct object { type }` + - `"programmatic"` - - `type: "direct"` + - `defer_loading: optional boolean` - The caller type. Always `direct`. + Whether this tool should be deferred and discovered via tool search. - - `"direct"` + - `description: optional string` - - `Program object { caller_id, type }` + Optional description of the custom tool, used to provide more context. - - `caller_id: string` + - `format: optional object { type } or object { definition, syntax, type }` - The call ID of the program item that produced this tool call. + The input format for the custom tool. Default is unconstrained text. - - `type: "program"` + - `Text object { type }` - The caller type. Always `program`. + Unconstrained free-form text. - - `"program"` + - `type: "text"` - - `created_by: optional string` + Unconstrained text format. Always `text`. - The identifier of the actor that created the item. + - `"text"` - - `AgentMessage object { id, author, content, 3 more }` + - `Grammar object { definition, syntax, type }` - - `id: string` + A grammar defined by the user. - The unique ID of the agent message. + - `definition: string` - - `author: string` + The grammar definition. - The sending agent identity. + - `syntax: "lark" or "regex"` - - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` + The syntax of the grammar definition. One of `lark` or `regex`. - Encrypted content sent between agents. + - `"lark"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `"regex"` - A text input to the model. + - `type: "grammar"` - - `BetaResponseOutputText object { annotations, logprobs, text, type }` + Grammar format. Always `grammar`. - A text output from the model. + - `"grammar"` - - `Text object { text, type }` + - `type: "namespace"` - A text content. + The type of the tool. Always `namespace`. - - `text: string` + - `"namespace"` - - `type: "text"` + - `ToolSearch object { type, description, execution, parameters }` - - `"text"` + Hosted or BYOT tool search configuration for deferred tools. - - `SummaryText object { text, type }` + - `type: "tool_search"` - A summary text from the model. + The type of the tool. Always `tool_search`. - - `text: string` + - `"tool_search"` - A summary of the reasoning output from the model so far. + - `description: optional string` - - `type: "summary_text"` + Description shown to the model for a client-executed tool search tool. - The type of the object. Always `summary_text`. + - `execution: optional "server" or "client"` - - `"summary_text"` + Whether tool search is executed by the server or by the client. - - `ReasoningText object { text, type }` + - `"server"` - Reasoning text from the model. + - `"client"` - - `text: string` + - `parameters: optional unknown` - The reasoning text from the model. + Parameter schema for a client-executed tool search tool. - - `type: "reasoning_text"` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - The type of the reasoning text. Always `reasoning_text`. + 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). - - `"reasoning_text"` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `BetaResponseOutputRefusal object { refusal, type }` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - A refusal from the model. + - `"web_search_preview"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `"web_search_preview_2025_03_11"` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `search_content_types: optional array of "text" or "image"` - - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` + - `"text"` - A screenshot of a computer. + - `"image"` - - `detail: "low" or "high" or "auto" or "original"` + - `search_context_size: optional "low" or "medium" or "high"` - The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - `"low"` - - `"high"` + - `"medium"` - - `"auto"` + - `"high"` - - `"original"` + - `user_location: optional object { type, city, country, 2 more }` - - `file_id: string` + The user's location. - The identifier of an uploaded file that contains the screenshot. + - `type: "approximate"` - - `image_url: string` + The type of location approximation. Always `approximate`. - The URL of the screenshot image. + - `"approximate"` - - `type: "computer_screenshot"` + - `city: optional string` - Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. + Free text input for the city of the user, e.g. `San Francisco`. - - `"computer_screenshot"` + - `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`. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `ApplyPatch object { type, allowed_callers }` - A file input to the model. + Allows the assistant to create, delete, or update files using unified diffs. - - `EncryptedContent object { encrypted_content, type }` + - `type: "apply_patch"` - Opaque encrypted content that Responses API decrypts inside trusted model execution. + The type of the tool. Always `apply_patch`. - - `encrypted_content: string` + - `"apply_patch"` - Opaque encrypted content. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "encrypted_content"` + The tool invocation context(s). - The type of the input item. Always `encrypted_content`. + - `"direct"` - - `"encrypted_content"` + - `"programmatic"` - - `recipient: string` + - `type: "additional_tools"` - The destination agent identity. + The item type. Always `additional_tools`. - - `type: "agent_message"` + - `"additional_tools"` - The type of the item. Always `agent_message`. + - `id: optional string` - - `"agent_message"` + The unique ID of this additional tools item. - `agent: optional object { agent_name }` @@ -205005,41 +205976,36 @@ curl https://api.openai.com/v1/responses/resp_abc123/input_items \ The canonical name of the agent that produced this item. - - `MultiAgentCall object { id, action, arguments, 3 more }` - - - `id: string` - - The unique ID of the multi-agent call item. - - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - The multi-agent action to execute. + - `Reasoning object { id, summary, type, 4 more }` - - `"spawn_agent"` + 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). - - `"interrupt_agent"` + - `id: string` - - `"list_agents"` + The unique identifier of the reasoning content. - - `"send_message"` + - `summary: array of object { text, type }` - - `"followup_task"` + Reasoning summary content. - - `"wait_agent"` + - `text: string` - - `arguments: string` + A summary of the reasoning output from the model so far. - The JSON string of arguments generated for the action. + - `type: "summary_text"` - - `call_id: string` + The type of the object. Always `summary_text`. - The unique ID linking this call to its output. + - `"summary_text"` - - `type: "multi_agent_call"` + - `type: "reasoning"` - The type of the multi-agent call. Always `multi_agent_call`. + The type of the object. Always `reasoning`. - - `"multi_agent_call"` + - `"reasoning"` - `agent: optional object { agent_name }` @@ -205049,55 +206015,54 @@ curl https://api.openai.com/v1/responses/resp_abc123/input_items \ The canonical name of the agent that produced this item. - - `MultiAgentCallOutput object { id, action, call_id, 3 more }` - - - `id: string` - - The unique ID of the multi-agent call output item. + - `content: optional array of object { text, type }` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + Reasoning text content. - The multi-agent action that produced this result. + - `text: string` - - `"spawn_agent"` + The reasoning text from the model. - - `"interrupt_agent"` + - `type: "reasoning_text"` - - `"list_agents"` + The type of the reasoning text. Always `reasoning_text`. - - `"send_message"` + - `"reasoning_text"` - - `"followup_task"` + - `encrypted_content: optional string` - - `"wait_agent"` + 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. - - `call_id: string` + - `status: optional "in_progress" or "completed" or "incomplete"` - The unique ID of the multi-agent call. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `output: array of BetaResponseOutputText` + - `"in_progress"` - Text output returned by the multi-agent action. + - `"completed"` - - `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 }` + - `"incomplete"` - The annotations of the text output. + - `Compaction object { encrypted_content, type, id, agent }` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - - `text: string` + - `encrypted_content: string` - The text output from the model. + The encrypted content of the compaction summary. - - `type: "output_text"` + - `type: "compaction"` - The type of the output text. Always `output_text`. + The type of the item. Always `compaction`. - - `type: "multi_agent_call_output"` + - `"compaction"` - The type of the multi-agent result. Always `multi_agent_call_output`. + - `id: optional string` - - `"multi_agent_call_output"` + The ID of the compaction item. - `agent: optional object { agent_name }` @@ -205107,43 +206072,35 @@ curl https://api.openai.com/v1/responses/resp_abc123/input_items \ The canonical name of the agent that produced this item. - - `ToolSearchCall object { id, arguments, call_id, 5 more }` - - - `id: string` - - The unique ID of the tool search call item. - - - `arguments: unknown` - - Arguments used for the tool search call. - - - `call_id: string` + - `ImageGenerationCall object { id, result, status, 2 more }` - The unique ID of the tool search call generated by the model. + An image generation request made by the model. - - `execution: "server" or "client"` + - `id: string` - Whether tool search was executed by the server or by the client. + The unique ID of the image generation call. - - `"server"` + - `result: string` - - `"client"` + The generated image encoded in base64. - - `status: "in_progress" or "completed" or "incomplete"` + - `status: "in_progress" or "completed" or "generating" or "failed"` - The status of the tool search call item that was recorded. + The status of the image generation call. - `"in_progress"` - `"completed"` - - `"incomplete"` + - `"generating"` - - `type: "tool_search_call"` + - `"failed"` - The type of the item. Always `tool_search_call`. + - `type: "image_generation_call"` - - `"tool_search_call"` + The type of the image generation call. Always `image_generation_call`. + + - `"image_generation_call"` - `agent: optional object { agent_name }` @@ -205153,2223 +206110,2157 @@ curl https://api.openai.com/v1/responses/resp_abc123/input_items \ The canonical name of the agent that produced this item. - - `created_by: optional string` - - The identifier of the actor that created the item. + - `CodeInterpreterCall object { id, code, container_id, 4 more }` - - `ToolSearchOutput object { id, call_id, execution, 5 more }` + A tool call to run code. - `id: string` - The unique ID of the tool search output item. + The unique ID of the code interpreter tool call. - - `call_id: string` + - `code: string` - The unique ID of the tool search call generated by the model. + The code to run, or null if not available. - - `execution: "server" or "client"` + - `container_id: string` - Whether tool search was executed by the server or by the client. + The ID of the container used to run the code. - - `"server"` + - `outputs: array of object { logs, type } or object { type, url }` - - `"client"` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `status: "in_progress" or "completed" or "incomplete"` + - `Logs object { logs, type }` - The status of the tool search output item that was recorded. + The logs output from the code interpreter. - - `"in_progress"` + - `logs: string` - - `"completed"` + The logs output from the code interpreter. - - `"incomplete"` + - `type: "logs"` - - `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 type of the output. Always `logs`. - The loaded tool definitions returned by tool search. + - `"logs"` - - `Function object { name, parameters, strict, 5 more }` + - `Image object { type, url }` - 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 image output from the code interpreter. - - `name: string` + - `type: "image"` - The name of the function to call. + The type of the output. Always `image`. - - `parameters: map[unknown]` + - `"image"` - A JSON schema object describing the parameters of the function. + - `url: string` - - `strict: boolean` + The URL of the image output from the code interpreter. - Whether strict parameter validation is enforced for this function tool. + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - `type: "function"` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - 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). + - `"interpreting"` - - `"direct"` + - `"failed"` - - `"programmatic"` + - `type: "code_interpreter_call"` - - `defer_loading: optional boolean` + The type of the code interpreter tool call. Always `code_interpreter_call`. - Whether this function is deferred and loaded via tool search. + - `"code_interpreter_call"` - - `description: optional string` + - `agent: optional object { agent_name }` - A description of the function. Used by the model to determine whether or not to call the function. + The agent that produced this item. - - `output_schema: optional map[unknown]` + - `agent_name: string` - A JSON schema object describing the JSON value encoded in string outputs for this function. + The canonical name of the agent that produced this item. - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + - `LocalShellCall object { id, action, call_id, 3 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). + A tool call to run a command on the local shell. - - `type: "file_search"` + - `id: string` - The type of the file search tool. Always `file_search`. + The unique ID of the local shell call. - - `"file_search"` + - `action: object { command, env, type, 3 more }` - - `vector_store_ids: array of string` + Execute a shell command on the server. - The IDs of the vector stores to search. + - `command: array of string` - - `filters: optional object { key, type, value } or object { filters, type }` + The command to run. - A filter to apply. + - `env: map[string]` - - `ComparisonFilter object { key, type, value }` + Environment variables to set for the command. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `type: "exec"` - - `key: string` + The type of the local shell action. Always `exec`. - The key to compare against the value. + - `"exec"` - - `type: "eq" or "ne" or "gt" or 5 more` + - `timeout_ms: optional number` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + Optional timeout in milliseconds for the command. - - `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 + - `user: optional string` - - `"eq"` + Optional user to run the command as. - - `"ne"` + - `working_directory: optional string` - - `"gt"` + Optional working directory to run the command in. - - `"gte"` + - `call_id: string` - - `"lt"` + The unique ID of the local shell tool call generated by the model. - - `"lte"` + - `status: "in_progress" or "completed" or "incomplete"` - - `"in"` + The status of the local shell call. - - `"nin"` + - `"in_progress"` - - `value: string or number or boolean or array of string or number` + - `"completed"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `"incomplete"` - - `string` + - `type: "local_shell_call"` - - `number` + The type of the local shell call. Always `local_shell_call`. - - `boolean` + - `"local_shell_call"` - - `array of string or number` + - `agent: optional object { agent_name }` - - `string` + The agent that produced this item. - - `number` + - `agent_name: string` - - `CompoundFilter object { filters, type }` + The canonical name of the agent that produced this item. - Combine multiple filters using `and` or `or`. + - `LocalShellCallOutput object { id, output, type, 2 more }` - - `filters: array of object { key, type, value } or unknown` + The output of a local shell tool call. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `id: string` - - `ComparisonFilter object { key, type, value }` + The unique ID of the local shell tool call generated by the model. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `output: string` - - `key: string` + A JSON string of the output of the local shell tool call. - The key to compare against the value. + - `type: "local_shell_call_output"` - - `type: "eq" or "ne" or "gt" or 5 more` + The type of the local shell tool call output. Always `local_shell_call_output`. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"local_shell_call_output"` - - `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 + - `agent: optional object { agent_name }` - - `"eq"` + The agent that produced this item. - - `"ne"` + - `agent_name: string` - - `"gt"` + The canonical name of the agent that produced this item. - - `"gte"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"lt"` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `"lte"` + - `"in_progress"` - - `"in"` + - `"completed"` - - `"nin"` + - `"incomplete"` - - `value: string or number or boolean or array of string or number` + - `ShellCall object { action, call_id, type, 5 more }` - The value to compare against the attribute key; supports string, number, or boolean types. + A tool representing a request to execute one or more shell commands. - - `string` + - `action: object { commands, max_output_length, timeout_ms }` - - `number` + The shell commands and limits that describe how to run the tool call. - - `boolean` + - `commands: array of string` - - `array of string or number` + Ordered shell commands for the execution environment to run. - - `string` + - `max_output_length: optional number` - - `number` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - - `unknown` + - `timeout_ms: optional number` - - `type: "and" or "or"` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - Type of operation: `and` or `or`. + - `call_id: string` - - `"and"` + The unique ID of the shell tool call generated by the model. - - `"or"` + - `type: "shell_call"` - - `max_num_results: optional number` + The type of the item. Always `shell_call`. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `"shell_call"` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `id: optional string` - Ranking options for search. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `agent: optional object { agent_name }` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + The agent that produced this item. - - `embedding_weight: number` + - `agent_name: string` - The weight of the embedding in the reciprocal ranking fusion. + The canonical name of the agent that produced this item. - - `text_weight: number` + - `caller: optional object { type } or object { caller_id, type }` - The weight of the text in the reciprocal ranking fusion. + The execution context that produced this tool call. - - `ranker: optional "auto" or "default-2024-11-15"` + - `Direct object { type }` - The ranker to use for the file search. + - `type: "direct"` - - `"auto"` + The caller type. Always `direct`. - - `"default-2024-11-15"` + - `"direct"` - - `score_threshold: optional number` + - `Program object { caller_id, type }` - 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. + - `caller_id: string` - - `Computer object { type }` + The call ID of the program item that produced this tool call. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `type: "program"` - - `type: "computer"` + The caller type. Always `program`. - The type of the computer tool. Always `computer`. + - `"program"` - - `"computer"` + - `environment: optional BetaLocalEnvironment or BetaContainerReference` - - `ComputerUsePreview object { display_height, display_width, environment, type }` + The environment to execute the shell commands in. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `BetaLocalEnvironment object { type, skills }` - - `display_height: number` + - `BetaContainerReference object { container_id, type }` - The height of the computer display. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `display_width: number` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - The width of the computer display. + - `"in_progress"` - - `environment: "windows" or "mac" or "linux" or 2 more` + - `"completed"` - The type of computer environment to control. + - `"incomplete"` - - `"windows"` + - `ShellCallOutput object { call_id, output, type, 5 more }` - - `"mac"` + The streamed output items emitted by a shell tool call. - - `"linux"` + - `call_id: string` - - `"ubuntu"` + The unique ID of the shell tool call generated by the model. - - `"browser"` + - `output: array of BetaResponseFunctionShellCallOutputContent` - - `type: "computer_use_preview"` + Captured chunks of stdout and stderr output, along with their associated outcomes. - The type of the computer use tool. Always `computer_use_preview`. + - `outcome: object { type } or object { exit_code, type }` - - `"computer_use_preview"` + The exit or timeout outcome associated with this shell call. - - `WebSearch object { type, filters, search_context_size, user_location }` + - `stderr: string` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + Captured stderr output for the shell call. - - `type: "web_search" or "web_search_2025_08_26"` + - `stdout: string` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + Captured stdout output for the shell call. - - `"web_search"` + - `type: "shell_call_output"` - - `"web_search_2025_08_26"` + The type of the item. Always `shell_call_output`. - - `filters: optional object { allowed_domains }` + - `"shell_call_output"` - Filters for the search. + - `id: optional string` - - `allowed_domains: optional array of string` + The unique ID of the shell tool call output. Populated when this item is returned via API. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `agent: optional object { agent_name }` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + The agent that produced this item. - - `search_context_size: optional "low" or "medium" or "high"` + - `agent_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 canonical name of the agent that produced this item. - - `"low"` + - `caller: optional object { type } or object { caller_id, type }` - - `"medium"` + The execution context that produced this tool call. - - `"high"` + - `Direct object { type }` - - `user_location: optional object { city, country, region, 2 more }` + - `type: "direct"` - The approximate location of the user. + The caller type. Always `direct`. - - `city: optional string` + - `"direct"` - Free text input for the city of the user, e.g. `San Francisco`. + - `Program object { caller_id, type }` - - `country: optional string` + - `caller_id: string` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The call ID of the program item that produced this tool call. - - `region: optional string` + - `type: "program"` - Free text input for the region of the user, e.g. `California`. + The caller type. Always `program`. - - `timezone: optional string` + - `"program"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `max_output_length: optional number` - - `type: optional "approximate"` + The maximum number of UTF-8 characters captured for this shell call's combined output. - The type of location approximation. Always `approximate`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"approximate"` + The status of the shell call output. - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `"in_progress"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + - `"completed"` - - `server_label: string` + - `"incomplete"` - A label for this MCP server, used to identify it in tool calls. + - `ApplyPatchCall object { call_id, operation, status, 4 more }` - - `type: "mcp"` + A tool call representing a request to create, delete, or update files using diff patches. - The type of the MCP tool. Always `mcp`. + - `call_id: string` - - `"mcp"` + The unique ID of the apply patch tool call generated by the model. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - The tool invocation context(s). + The specific create, delete, or update instruction for the apply_patch tool call. - - `"direct"` + - `CreateFile object { diff, path, type }` - - `"programmatic"` + Instruction for creating a new file via the apply_patch tool. - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `diff: string` - List of allowed tool names or a filter object. + Unified diff content to apply when creating the file. - - `McpAllowedTools = array of string` + - `path: string` - A string array of allowed tool names + Path of the file to create relative to the workspace root. - - `McpToolFilter object { read_only, tool_names }` + - `type: "create_file"` - A filter object to specify which tools are allowed. + The operation type. Always `create_file`. - - `read_only: optional boolean` + - `"create_file"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `DeleteFile object { path, type }` - - `tool_names: optional array of string` + Instruction for deleting an existing file via the apply_patch tool. - List of allowed tool names. + - `path: string` - - `authorization: optional string` + Path of the file to delete relative to the workspace root. - An OAuth access token that can be used with a remote MCP server, either - with a custom MCP server URL or a service connector. Your application - must handle the OAuth authorization flow and provide the token here. + - `type: "delete_file"` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + The operation type. Always `delete_file`. - 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). + - `"delete_file"` - Currently supported `connector_id` values are: + - `UpdateFile object { diff, path, type }` - - 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` + Instruction for updating an existing file via the apply_patch tool. - - `"connector_dropbox"` + - `diff: string` - - `"connector_gmail"` + Unified diff content to apply to the existing file. - - `"connector_googlecalendar"` + - `path: string` - - `"connector_googledrive"` + Path of the file to update relative to the workspace root. - - `"connector_microsoftteams"` + - `type: "update_file"` - - `"connector_outlookcalendar"` + The operation type. Always `update_file`. - - `"connector_outlookemail"` + - `"update_file"` - - `"connector_sharepoint"` + - `status: "in_progress" or "completed"` - - `defer_loading: optional boolean` + The status of the apply patch tool call. One of `in_progress` or `completed`. - Whether this MCP tool is deferred and discovered via tool search. + - `"in_progress"` - - `headers: optional map[string]` + - `"completed"` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `type: "apply_patch_call"` - - `require_approval: optional object { always, never } or "always" or "never"` + The type of the item. Always `apply_patch_call`. - Specify which of the MCP server's tools require approval. + - `"apply_patch_call"` - - `McpToolApprovalFilter object { always, never }` + - `id: 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 unique ID of the apply patch tool call. Populated when this item is returned via API. - - `always: optional object { read_only, tool_names }` + - `agent: optional object { agent_name }` - A filter object to specify which tools are allowed. + The agent that produced this item. - - `read_only: optional boolean` + - `agent_name: string` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + The canonical name of the agent that produced this item. - - `tool_names: optional array of string` + - `caller: optional object { type } or object { caller_id, type }` - List of allowed tool names. + The execution context that produced this tool call. - - `never: optional object { read_only, tool_names }` + - `Direct object { type }` - A filter object to specify which tools are allowed. + - `type: "direct"` - - `read_only: optional boolean` + The caller type. Always `direct`. - 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"` - - `tool_names: optional array of string` + - `Program object { caller_id, type }` - List of allowed tool names. + - `caller_id: string` - - `McpToolApprovalSetting = "always" or "never"` + The call ID of the program item that produced this tool call. - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `type: "program"` - - `"always"` + The caller type. Always `program`. - - `"never"` + - `"program"` - - `server_description: optional string` + - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` - Optional description of the MCP server, used to provide more context. + The streamed output emitted by an apply patch tool call. - - `server_url: optional string` + - `call_id: string` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + The unique ID of the apply patch tool call generated by the model. - - `tunnel_id: optional string` + - `status: "completed" or "failed"` - 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 status of the apply patch tool call output. One of `completed` or `failed`. - - `CodeInterpreter object { container, type, allowed_callers }` + - `"completed"` - A tool that runs Python code to help generate a response to a prompt. + - `"failed"` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `type: "apply_patch_call_output"` - The code interpreter container. Can be a container ID or an object that - specifies uploaded file IDs to make available to your code, along with an - optional `memory_limit` setting. + The type of the item. Always `apply_patch_call_output`. - - `string` + - `"apply_patch_call_output"` - The container ID. + - `id: optional string` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `agent: optional object { agent_name }` - - `type: "auto"` + The agent that produced this item. - Always `auto`. + - `agent_name: string` - - `"auto"` + The canonical name of the agent that produced this item. - - `file_ids: optional array of string` + - `caller: optional object { type } or object { caller_id, type }` - An optional list of uploaded files to make available to your code. + The execution context that produced this tool call. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `Direct object { type }` - The memory limit for the code interpreter container. + - `type: "direct"` - - `"1g"` + The caller type. Always `direct`. - - `"4g"` + - `"direct"` - - `"16g"` + - `Program object { caller_id, type }` - - `"64g"` + - `caller_id: string` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + The call ID of the program item that produced this tool call. - Network access policy for the container. + - `type: "program"` - - `BetaContainerNetworkPolicyDisabled object { type }` + The caller type. Always `program`. - - `type: "disabled"` + - `"program"` - Disable outbound network access. Always `disabled`. + - `output: optional string` - - `"disabled"` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `McpListTools object { id, server_label, tools, 3 more }` - - `allowed_domains: array of string` + A list of tools available on an MCP server. - A list of allowed domains when type is `allowlist`. + - `id: string` - - `type: "allowlist"` + The unique ID of the list. - Allow outbound network access only to specified domains. Always `allowlist`. + - `server_label: string` - - `"allowlist"` + The label of the MCP server. - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + - `tools: array of object { input_schema, name, annotations, description }` - Optional domain-scoped secrets for allowlisted domains. + The tools available on the server. - - `domain: string` + - `input_schema: unknown` - The domain associated with the secret. + The JSON schema describing the tool's input. - `name: string` - The name of the secret to inject for the domain. - - - `value: string` - - The secret value to inject for the domain. - - - `type: "code_interpreter"` - - The type of the code interpreter tool. Always `code_interpreter`. - - - `"code_interpreter"` - - - `allowed_callers: optional array of "direct" or "programmatic"` - - The tool invocation context(s). - - - `"direct"` - - - `"programmatic"` + The name of the tool. - - `ProgrammaticToolCalling object { type }` + - `annotations: optional unknown` - - `type: "programmatic_tool_calling"` + Additional annotations about the tool. - The type of the tool. Always `programmatic_tool_calling`. + - `description: optional string` - - `"programmatic_tool_calling"` + The description of the tool. - - `ImageGeneration object { type, action, background, 9 more }` + - `type: "mcp_list_tools"` - A tool that generates images using the GPT image models. + The type of the item. Always `mcp_list_tools`. - - `type: "image_generation"` + - `"mcp_list_tools"` - The type of the image generation tool. Always `image_generation`. + - `agent: optional object { agent_name }` - - `"image_generation"` + The agent that produced this item. - - `action: optional "generate" or "edit" or "auto"` + - `agent_name: string` - Whether to generate a new image or edit an existing image. Default: `auto`. + The canonical name of the agent that produced this item. - - `"generate"` + - `error: optional string` - - `"edit"` + Error message if the server could not list tools. - - `"auto"` + - `McpApprovalRequest object { id, arguments, name, 3 more }` - - `background: optional "transparent" or "opaque" or "auto"` + A request for human approval of a tool invocation. - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + - `id: string` - - `"transparent"` + The unique ID of the approval request. - - `"opaque"` + - `arguments: string` - - `"auto"` + A JSON string of arguments for the tool. - - `input_fidelity: optional "high" or "low"` + - `name: 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 name of the tool to run. - - `"high"` + - `server_label: string` - - `"low"` + The label of the MCP server making the request. - - `input_image_mask: optional object { file_id, image_url }` + - `type: "mcp_approval_request"` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + The type of the item. Always `mcp_approval_request`. - - `file_id: optional string` + - `"mcp_approval_request"` - File ID for the mask image. + - `agent: optional object { agent_name }` - - `image_url: optional string` + The agent that produced this item. - Base64-encoded mask image. + - `agent_name: string` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + The canonical name of the agent that produced this item. - The image generation model to use. Default: `gpt-image-1`. + - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` - - `string` + A response to an MCP approval request. - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `approval_request_id: string` - The image generation model to use. Default: `gpt-image-1`. + The ID of the approval request being answered. - - `"gpt-image-1"` + - `approve: boolean` - - `"gpt-image-1-mini"` + Whether the request was approved. - - `"gpt-image-1.5"` + - `type: "mcp_approval_response"` - - `moderation: optional "auto" or "low"` + The type of the item. Always `mcp_approval_response`. - Moderation level for the generated image. Default: `auto`. + - `"mcp_approval_response"` - - `"auto"` + - `id: optional string` - - `"low"` + The unique ID of the approval response - - `output_compression: optional number` + - `agent: optional object { agent_name }` - Compression level for the output image. Default: 100. + The agent that produced this item. - - `output_format: optional "png" or "webp" or "jpeg"` + - `agent_name: string` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + The canonical name of the agent that produced this item. - - `"png"` + - `reason: optional string` - - `"webp"` + Optional reason for the decision. - - `"jpeg"` + - `McpCall object { id, arguments, name, 7 more }` - - `partial_images: optional number` + An invocation of a tool on an MCP server. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `id: string` - - `quality: optional "low" or "medium" or "high" or "auto"` + The unique ID of the tool call. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `arguments: string` - - `"low"` + A JSON string of the arguments passed to the tool. - - `"medium"` + - `name: string` - - `"high"` + The name of the tool that was run. - - `"auto"` + - `server_label: string` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The label of the MCP server running the tool. - 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: "mcp_call"` - - `string` + The type of the item. Always `mcp_call`. - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `"mcp_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`. + - `agent: optional object { agent_name }` - - `"1024x1024"` + The agent that produced this item. - - `"1024x1536"` + - `agent_name: string` - - `"1536x1024"` + The canonical name of the agent that produced this item. - - `"auto"` + - `approval_request_id: optional string` - - `LocalShell object { type }` + 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 tool that allows the model to execute shell commands in a local environment. + - `error: optional string` - - `type: "local_shell"` + The error from the tool call, if any. - The type of the local shell tool. Always `local_shell`. + - `output: optional string` - - `"local_shell"` + The output from the tool call. - - `Shell object { type, allowed_callers, environment }` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - A tool that allows the model to execute shell commands. + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `type: "shell"` + - `"in_progress"` - The type of the shell tool. Always `shell`. + - `"completed"` - - `"shell"` + - `"incomplete"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"calling"` - The tool invocation context(s). + - `"failed"` - - `"direct"` + - `CustomToolCallOutput object { call_id, output, type, 3 more }` - - `"programmatic"` + The output of a custom tool call from your code, being sent back to the model. - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `call_id: string` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + The call ID, used to map this custom tool call output to a custom tool call. - - `type: "container_auto"` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - Automatically creates a container for this request + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `"container_auto"` + - `StringOutput = string` - - `file_ids: optional array of string` + A string of the output of the custom tool call. - An optional list of uploaded files to make available to your code. + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + Text, image, or file output of the custom tool call. - The memory limit for the container. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `"1g"` + A text input to the model. - - `"4g"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `"16g"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"64g"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + A file input to the model. - Network access policy for the container. + - `type: "custom_tool_call_output"` - - `BetaContainerNetworkPolicyDisabled object { type }` + The type of the custom tool call output. Always `custom_tool_call_output`. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `"custom_tool_call_output"` - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + - `id: optional string` - An optional list of skills referenced by id or inline data. + The unique ID of the custom tool call output in the OpenAI platform. - - `BetaSkillReference object { skill_id, type, version }` + - `agent: optional object { agent_name }` - - `skill_id: string` + The agent that produced this item. - The ID of the referenced skill. + - `agent_name: string` - - `type: "skill_reference"` + The canonical name of the agent that produced this item. - References a skill created with the /v1/skills endpoint. + - `caller: optional object { type } or object { caller_id, type }` - - `"skill_reference"` + The execution context that produced this tool call. - - `version: optional string` + - `Direct object { type }` - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `type: "direct"` - - `BetaInlineSkill object { description, name, source, type }` + The caller type. Always `direct`. - - `description: string` + - `"direct"` - The description of the skill. + - `Program object { caller_id, type }` - - `name: string` + - `caller_id: string` - The name of the skill. + The call ID of the program item that produced this tool call. - - `source: BetaInlineSkillSource` + - `type: "program"` - Inline skill payload + The caller type. Always `program`. - - `data: string` + - `"program"` - Base64-encoded skill zip bundle. + - `CustomToolCall object { call_id, input, name, 5 more }` - - `media_type: "application/zip"` + A call to a custom tool created by the model. - The media type of the inline skill payload. Must be `application/zip`. + - `call_id: string` - - `"application/zip"` + An identifier used to map this custom tool call to a tool call output. - - `type: "base64"` + - `input: string` - The type of the inline skill source. Must be `base64`. + The input for the custom tool call generated by the model. - - `"base64"` + - `name: string` - - `type: "inline"` + The name of the custom tool being called. - Defines an inline skill for this request. + - `type: "custom_tool_call"` - - `"inline"` + The type of the custom tool call. Always `custom_tool_call`. - - `BetaLocalEnvironment object { type, skills }` + - `"custom_tool_call"` - - `type: "local"` + - `id: optional string` - Use a local computer environment. + The unique ID of the custom tool call in the OpenAI platform. - - `"local"` + - `agent: optional object { agent_name }` - - `skills: optional array of BetaLocalSkill` + The agent that produced this item. - An optional list of skills. + - `agent_name: string` - - `description: string` + The canonical name of the agent that produced this item. - The description of the skill. + - `caller: optional object { type } or object { caller_id, type }` - - `name: string` + The execution context that produced this tool call. - The name of the skill. + - `Direct object { type }` - - `path: string` + - `type: "direct"` - The path to the directory containing the skill. + - `"direct"` - - `BetaContainerReference object { container_id, type }` + - `Program object { caller_id, type }` - - `container_id: string` + - `caller_id: string` - The ID of the referenced container. + The call ID of the program item that produced this tool call. - - `type: "container_reference"` + - `type: "program"` - References a container created with the /v1/containers endpoint + - `"program"` - - `"container_reference"` + - `namespace: optional string` - - `Custom object { name, type, allowed_callers, 3 more }` + The namespace of the custom tool being called. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `CompactionTrigger object { type, agent }` - - `name: string` + Compacts the current context. Must be the final input item. - The name of the custom tool, used to identify it in tool calls. + - `type: "compaction_trigger"` - - `type: "custom"` + The type of the item. Always `compaction_trigger`. - The type of the custom tool. Always `custom`. + - `"compaction_trigger"` - - `"custom"` + - `agent: optional object { agent_name }` - - `allowed_callers: optional array of "direct" or "programmatic"` + The agent that produced this item. - The tool invocation context(s). + - `agent_name: string` - - `"direct"` + The canonical name of the agent that produced this item. - - `"programmatic"` + - `ItemReference object { id, agent, type }` - - `defer_loading: optional boolean` + An internal identifier for an item to reference. - Whether this tool should be deferred and discovered via tool search. + - `id: string` - - `description: optional string` + The ID of the item to reference. - Optional description of the custom tool, used to provide more context. + - `agent: optional object { agent_name }` - - `format: optional object { type } or object { definition, syntax, type }` + The agent that produced this item. - The input format for the custom tool. Default is unconstrained text. + - `agent_name: string` - - `Text object { type }` + The canonical name of the agent that produced this item. - Unconstrained free-form text. + - `type: optional "item_reference"` - - `type: "text"` + The type of item to reference. Always `item_reference`. - Unconstrained text format. Always `text`. + - `"item_reference"` - - `"text"` + - `Program object { id, call_id, code, 3 more }` - - `Grammar object { definition, syntax, type }` + - `id: string` - A grammar defined by the user. + The unique ID of this program item. - - `definition: string` + - `call_id: string` - The grammar definition. + The stable call ID of the program item. - - `syntax: "lark" or "regex"` + - `code: string` - The syntax of the grammar definition. One of `lark` or `regex`. + The JavaScript source executed by programmatic tool calling. - - `"lark"` + - `fingerprint: string` - - `"regex"` + Opaque program replay fingerprint that must be round-tripped. - - `type: "grammar"` + - `type: "program"` - Grammar format. Always `grammar`. + The item type. Always `program`. - - `"grammar"` + - `"program"` - - `Namespace object { description, name, tools, type }` + - `agent: optional object { agent_name }` - Groups function/custom tools under a shared namespace. + The agent that produced this item. - - `description: string` + - `agent_name: string` - A description of the namespace shown to the model. + The canonical name of the agent that produced this item. - - `name: string` + - `ProgramOutput object { id, call_id, result, 3 more }` - 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 this program output item. - The function/custom tools available inside this namespace. + - `call_id: string` - - `Function object { name, type, allowed_callers, 5 more }` + The call ID of the program item. - - `name: string` + - `result: string` - - `type: "function"` + The result produced by the program item. - - `"function"` + - `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"` - - `defer_loading: optional boolean` + The item type. Always `program_output`. - Whether this function should be deferred and discovered via tool search. + - `"program_output"` - - `description: optional string` + - `agent: optional object { agent_name }` - - `output_schema: optional map[unknown]` + The agent that produced this item. - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `agent_name: string` - - `parameters: optional unknown` + The canonical name of the agent that produced this item. - - `strict: optional boolean` + - `response_id: string` - 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 ID of the response that rejected the input. - - `Custom object { name, type, allowed_callers, 3 more }` + - `sequence_number: number` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + The sequence number for this event. - - `name: string` + - `type: "response.inject.failed"` - The name of the custom tool, used to identify it in tool calls. + The event discriminator. Always `response.inject.failed`. - - `type: "custom"` + - `"response.inject.failed"` - The type of the custom tool. Always `custom`. + - `stream_id: optional string` - - `"custom"` + The multiplexed WebSocket stream that emitted the event. This field is + present only when WebSocket multiplexing is enabled separately. - - `allowed_callers: optional array of "direct" or "programmatic"` +### Beta Skill Reference - The tool invocation context(s). +- `BetaSkillReference object { skill_id, type, version }` - - `"direct"` + - `skill_id: string` - - `"programmatic"` + The ID of the referenced skill. - - `defer_loading: optional boolean` + - `type: "skill_reference"` - Whether this tool should be deferred and discovered via tool search. + References a skill created with the /v1/skills endpoint. - - `description: optional string` + - `"skill_reference"` - Optional description of the custom tool, used to provide more context. + - `version: optional string` - - `format: optional object { type } or object { definition, syntax, type }` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - The input format for the custom tool. Default is unconstrained text. +### Beta Tool Choice Allowed - - `Text object { type }` +- `BetaToolChoiceAllowed object { mode, tools, type }` - Unconstrained free-form text. + Constrains the tools available to the model to a pre-defined set. - - `type: "text"` + - `mode: "auto" or "required"` - Unconstrained text format. Always `text`. + Constrains the tools available to the model to a pre-defined set. - - `"text"` + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `Grammar object { definition, syntax, type }` + `required` requires the model to call one or more of the allowed tools. - A grammar defined by the user. + - `"auto"` - - `definition: string` + - `"required"` - The grammar definition. + - `tools: array of map[unknown]` - - `syntax: "lark" or "regex"` + A list of tool definitions that the model should be allowed to call. - The syntax of the grammar definition. One of `lark` or `regex`. + For the Responses API, the list of tool definitions might look like: - - `"lark"` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `"regex"` + - `type: "allowed_tools"` - - `type: "grammar"` + Allowed tool configuration type. Always `allowed_tools`. - Grammar format. Always `grammar`. + - `"allowed_tools"` - - `"grammar"` +### Beta Tool Choice Apply Patch - - `type: "namespace"` +- `BetaToolChoiceApplyPatch object { type }` - The type of the tool. Always `namespace`. + Forces the model to call the apply_patch tool when executing a tool call. - - `"namespace"` + - `type: "apply_patch"` - - `ToolSearch object { type, description, execution, parameters }` + The tool to call. Always `apply_patch`. - Hosted or BYOT tool search configuration for deferred tools. + - `"apply_patch"` - - `type: "tool_search"` +### Beta Tool Choice Custom - The type of the tool. Always `tool_search`. +- `BetaToolChoiceCustom object { name, type }` - - `"tool_search"` + Use this option to force the model to call a specific custom tool. - - `description: optional string` + - `name: string` - Description shown to the model for a client-executed tool search tool. + The name of the custom tool to call. - - `execution: optional "server" or "client"` + - `type: "custom"` - Whether tool search is executed by the server or by the client. + For custom tool calling, the type is always `custom`. - - `"server"` + - `"custom"` - - `"client"` +### Beta Tool Choice Function - - `parameters: optional unknown` +- `BetaToolChoiceFunction object { name, type }` - Parameter schema for a client-executed tool search tool. + Use this option to force the model to call a specific function. - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `name: 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 name of the function to call. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `type: "function"` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + For function calling, the type is always `function`. - - `"web_search_preview"` + - `"function"` - - `"web_search_preview_2025_03_11"` +### Beta Tool Choice Mcp - - `search_content_types: optional array of "text" or "image"` +- `BetaToolChoiceMcp object { server_label, type, name }` - - `"text"` + Use this option to force the model to call a specific tool on a remote MCP server. - - `"image"` + - `server_label: string` - - `search_context_size: optional "low" or "medium" or "high"` + The label of the MCP server to use. - 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"` - - `"low"` + For MCP tools, the type is always `mcp`. - - `"medium"` + - `"mcp"` - - `"high"` + - `name: optional string` - - `user_location: optional object { type, city, country, 2 more }` + The name of the tool to call on the server. - The user's location. +### Beta Tool Choice Options - - `type: "approximate"` +- `BetaToolChoiceOptions = "none" or "auto" or "required"` - The type of location approximation. Always `approximate`. + Controls which (if any) tool is called by the model. - - `"approximate"` + `none` means the model will not call any tool and instead generates a message. - - `city: optional string` + `auto` means the model can pick between generating a message or calling one or + more tools. - Free text input for the city of the user, e.g. `San Francisco`. + `required` means the model must call one or more tools. - - `country: optional string` + - `"none"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `"auto"` - - `region: optional string` + - `"required"` - Free text input for the region of the user, e.g. `California`. +### Beta Tool Choice Shell - - `timezone: optional string` +- `BetaToolChoiceShell object { type }` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + Forces the model to call the shell tool when a tool call is required. - - `ApplyPatch object { type, allowed_callers }` + - `type: "shell"` - Allows the assistant to create, delete, or update files using unified diffs. + The tool to call. Always `shell`. - - `type: "apply_patch"` + - `"shell"` - The type of the tool. Always `apply_patch`. +### Beta Tool Choice Types - - `"apply_patch"` +- `BetaToolChoiceTypes object { type }` - - `allowed_callers: optional array of "direct" or "programmatic"` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](/docs/guides/tools). - The tool invocation context(s). + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` - - `"direct"` + The type of hosted tool the model should to use. Learn more about + [built-in tools](/docs/guides/tools). - - `"programmatic"` + Allowed values are: - - `type: "tool_search_output"` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - The type of the item. Always `tool_search_output`. + - `"file_search"` - - `"tool_search_output"` + - `"web_search_preview"` - - `agent: optional object { agent_name }` + - `"computer"` - The agent that produced this item. + - `"computer_use_preview"` - - `agent_name: string` + - `"computer_use"` - The canonical name of the agent that produced this item. + - `"web_search_preview_2025_03_11"` - - `created_by: optional string` + - `"image_generation"` - The identifier of the actor that created the item. + - `"code_interpreter"` - - `AdditionalTools object { id, role, tools, 2 more }` +# Input Items - - `id: string` +## List input items - The unique ID of the additional tools item. +**get** `/responses/{response_id}/input_items?beta=true` - - `role: "unknown" or "user" or "assistant" or 5 more` +Returns a list of input items for a given response. - The role that provided the additional tools. +### Header Parameters - - `"unknown"` +- `"openai-beta": optional array of "responses_multi_agent=v1"` - - `"user"` + - `"responses_multi_agent=v1"` - - `"assistant"` +### Path Parameters - - `"system"` +- `response_id: string` - - `"critic"` +### Query Parameters - - `"discriminator"` +- `after: optional string` - - `"developer"` + An item ID to list items after, used in pagination. - - `"tool"` +- `include: optional array of BetaResponseIncludable` - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + Additional fields to include in the response. See the `include` + parameter for Response creation above for more information. - The additional tool definitions made available at this item. + - `"file_search_call.results"` - - `Function object { name, parameters, strict, 5 more }` + - `"web_search_call.results"` - 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). + - `"web_search_call.action.sources"` - - `name: string` + - `"message.input_image.image_url"` - The name of the function to call. + - `"computer_call_output.output.image_url"` - - `parameters: map[unknown]` + - `"code_interpreter_call.outputs"` - A JSON schema object describing the parameters of the function. + - `"reasoning.encrypted_content"` - - `strict: boolean` + - `"message.output_text.logprobs"` - Whether strict parameter validation is enforced for this function tool. +- `limit: optional number` - - `type: "function"` + A limit on the number of objects to be returned. Limit can range between + 1 and 100, and the default is 20. - The type of the function tool. Always `function`. +- `order: optional "asc" or "desc"` - - `"function"` + The order to return the input items in. Default is `desc`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `asc`: Return the input items in ascending order. + - `desc`: Return the input items in descending order. - The tool invocation context(s). + - `"asc"` - - `"direct"` + - `"desc"` - - `"programmatic"` +### Returns - - `defer_loading: optional boolean` +- `BetaResponseItemList object { data, first_id, has_more, 2 more }` - Whether this function is deferred and loaded via tool search. + A list of Response items. - - `description: optional string` + - `data: array of BetaResponseInputMessageItem or BetaResponseOutputMessage or object { id, queries, status, 3 more } or 29 more` - A description of the function. Used by the model to determine whether or not to call the function. + A list of items used to generate this response. - - `output_schema: optional map[unknown]` + - `BetaResponseInputMessageItem object { id, content, role, 3 more }` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `id: string` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + The unique ID of the message input. - 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). + - `content: BetaResponseInputMessageContentList` - - `type: "file_search"` + A list of one or many input items to the model, containing different content + types. - The type of the file search tool. Always `file_search`. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `"file_search"` + A text input to the model. - - `vector_store_ids: array of string` + - `text: string` - The IDs of the vector stores to search. + The text input to the model. - - `filters: optional object { key, type, value } or object { filters, type }` + - `type: "input_text"` - A filter to apply. + The type of the input item. Always `input_text`. - - `ComparisonFilter object { key, type, value }` + - `"input_text"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `prompt_cache_breakpoint: optional object { mode }` - - `key: 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 key to compare against the value. + - `mode: "explicit"` - - `type: "eq" or "ne" or "gt" or 5 more` + The breakpoint mode. Always `explicit`. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `"explicit"` - - `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 + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `"eq"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"ne"` + - `detail: "low" or "high" or "auto" or "original"` - - `"gt"` + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `"gte"` + - `"low"` - - `"lt"` + - `"high"` - - `"lte"` + - `"auto"` - - `"in"` + - `"original"` - - `"nin"` + - `type: "input_image"` - - `value: string or number or boolean or array of string or number` + The type of the input item. Always `input_image`. - The value to compare against the attribute key; supports string, number, or boolean types. + - `"input_image"` - - `string` + - `file_id: optional string` - - `number` + The ID of the file to be sent to the model. - - `boolean` + - `image_url: optional string` - - `array of string or number` + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `string` + - `prompt_cache_breakpoint: optional object { mode }` - - `number` + 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. - - `CompoundFilter object { filters, type }` + - `mode: "explicit"` - Combine multiple filters using `and` or `or`. + The breakpoint mode. Always `explicit`. - - `filters: array of object { key, type, value } or unknown` + - `"explicit"` - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `ComparisonFilter object { key, type, value }` + A file input to the model. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `type: "input_file"` - - `key: string` + The type of the input item. Always `input_file`. - The key to compare against the value. + - `"input_file"` - - `type: "eq" or "ne" or "gt" or 5 more` + - `detail: optional "auto" or "low" or "high"` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + 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`. - - `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 + - `"auto"` - - `"eq"` + - `"low"` - - `"ne"` + - `"high"` - - `"gt"` + - `file_data: optional string` - - `"gte"` + The content of the file to be sent to the model. - - `"lt"` + - `file_id: optional string` - - `"lte"` + The ID of the file to be sent to the model. - - `"in"` + - `file_url: optional string` - - `"nin"` + The URL of the file to be sent to the model. - - `value: string or number or boolean or array of string or number` + - `filename: optional string` - The value to compare against the attribute key; supports string, number, or boolean types. + The name of the file to be sent to the model. - - `string` + - `prompt_cache_breakpoint: optional object { mode }` - - `number` + 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. - - `boolean` + - `mode: "explicit"` - - `array of string or number` + The breakpoint mode. Always `explicit`. - - `string` + - `"explicit"` - - `number` + - `role: "user" or "system" or "developer"` - - `unknown` + The role of the message input. One of `user`, `system`, or `developer`. - - `type: "and" or "or"` + - `"user"` - Type of operation: `and` or `or`. + - `"system"` - - `"and"` + - `"developer"` - - `"or"` + - `type: "message"` - - `max_num_results: optional number` + The type of the message input. Always set to `message`. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `"message"` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `agent: optional object { agent_name }` - Ranking options for search. + The agent that produced this item. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `agent_name: string` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + The canonical name of the agent that produced this item. - - `embedding_weight: number` + - `status: optional "in_progress" or "completed" or "incomplete"` - The weight of the embedding in the reciprocal ranking fusion. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `text_weight: number` + - `"in_progress"` - The weight of the text in the reciprocal ranking fusion. + - `"completed"` - - `ranker: optional "auto" or "default-2024-11-15"` + - `"incomplete"` - The ranker to use for the file search. + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - - `"auto"` + An output message from the model. - - `"default-2024-11-15"` + - `id: string` - - `score_threshold: optional number` + The unique ID of the output message. - The score threshold for the file search, a number between 0 and 1. Numbers closer to 1 will attempt to return only the most relevant results, but may return fewer results. + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - - `Computer object { type }` + The content of the output message. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - - `type: "computer"` + A text output from the model. - The type of the computer tool. Always `computer`. + - `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 }` - - `"computer"` + The annotations of the text output. - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `FileCitation object { file_id, filename, index, type }` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + A citation to a file. - - `display_height: number` + - `file_id: string` - The height of the computer display. + The ID of the file. - - `display_width: number` + - `filename: string` - The width of the computer display. + The filename of the file cited. - - `environment: "windows" or "mac" or "linux" or 2 more` + - `index: number` - The type of computer environment to control. + The index of the file in the list of files. - - `"windows"` + - `type: "file_citation"` - - `"mac"` + The type of the file citation. Always `file_citation`. - - `"linux"` + - `"file_citation"` - - `"ubuntu"` + - `URLCitation object { end_index, start_index, title, 2 more }` - - `"browser"` + A citation for a web resource used to generate a model response. - - `type: "computer_use_preview"` + - `end_index: number` - The type of the computer use tool. Always `computer_use_preview`. + The index of the last character of the URL citation in the message. - - `"computer_use_preview"` + - `start_index: number` - - `WebSearch object { type, filters, search_context_size, user_location }` + The index of the first character of the URL citation in the message. - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + - `title: string` - - `type: "web_search" or "web_search_2025_08_26"` + The title of the web resource. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `type: "url_citation"` - - `"web_search"` + The type of the URL citation. Always `url_citation`. - - `"web_search_2025_08_26"` + - `"url_citation"` - - `filters: optional object { allowed_domains }` + - `url: string` - Filters for the search. + The URL of the web resource. - - `allowed_domains: optional array of string` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + A citation for a container file used to generate a model response. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `container_id: string` - - `search_context_size: optional "low" or "medium" or "high"` + The ID of the container file. - 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. + - `end_index: number` - - `"low"` + The index of the last character of the container file citation in the message. - - `"medium"` + - `file_id: string` - - `"high"` + The ID of the file. - - `user_location: optional object { city, country, region, 2 more }` + - `filename: string` - The approximate location of the user. + The filename of the container file cited. - - `city: optional string` + - `start_index: number` - Free text input for the city of the user, e.g. `San Francisco`. + The index of the first character of the container file citation in the message. - - `country: optional string` + - `type: "container_file_citation"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The type of the container file citation. Always `container_file_citation`. - - `region: optional string` + - `"container_file_citation"` - Free text input for the region of the user, e.g. `California`. + - `FilePath object { file_id, index, type }` - - `timezone: optional string` + A path to a file. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `file_id: string` - - `type: optional "approximate"` + The ID of the file. - The type of location approximation. Always `approximate`. + - `index: number` - - `"approximate"` + The index of the file in the list of files. - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `type: "file_path"` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + The type of the file path. Always `file_path`. - - `server_label: string` + - `"file_path"` - A label for this MCP server, used to identify it in tool calls. + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - - `type: "mcp"` + - `token: string` - The type of the MCP tool. Always `mcp`. + - `bytes: array of number` - - `"mcp"` + - `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` - - `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 output from the model. - - `McpAllowedTools = array of string` + - `type: "output_text"` - A string array of allowed tool names + The type of the output text. Always `output_text`. - - `McpToolFilter object { read_only, tool_names }` + - `"output_text"` - A filter object to specify which tools are allowed. + - `BetaResponseOutputRefusal object { refusal, type }` - - `read_only: optional boolean` + A refusal from 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. + - `refusal: string` - - `tool_names: optional array of string` + The refusal explanation from the model. - List of allowed tool names. + - `type: "refusal"` - - `authorization: optional string` + The type of the refusal. Always `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. + - `"refusal"` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `role: "assistant"` - 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 role of the output message. Always `assistant`. - Currently supported `connector_id` values are: + - `"assistant"` - - Dropbox: `connector_dropbox` - - Gmail: `connector_gmail` - - Google Calendar: `connector_googlecalendar` - - Google Drive: `connector_googledrive` - - Microsoft Teams: `connector_microsoftteams` - - Outlook Calendar: `connector_outlookcalendar` - - Outlook Email: `connector_outlookemail` - - SharePoint: `connector_sharepoint` + - `status: "in_progress" or "completed" or "incomplete"` - - `"connector_dropbox"` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `"connector_gmail"` + - `"in_progress"` - - `"connector_googlecalendar"` + - `"completed"` - - `"connector_googledrive"` + - `"incomplete"` - - `"connector_microsoftteams"` + - `type: "message"` - - `"connector_outlookcalendar"` + The type of the output message. Always `message`. - - `"connector_outlookemail"` + - `"message"` - - `"connector_sharepoint"` + - `agent: optional object { agent_name }` - - `defer_loading: optional boolean` + The agent that produced this item. - Whether this MCP tool is deferred and discovered via tool search. + - `agent_name: string` - - `headers: optional map[string]` + The canonical name of the agent that produced this item. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `phase: optional "commentary" or "final_answer"` - - `require_approval: optional object { always, never } or "always" or "never"` + 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. - Specify which of the MCP server's tools require approval. + - `"commentary"` - - `McpToolApprovalFilter object { always, never }` + - `"final_answer"` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `FileSearchCall object { id, queries, status, 3 more }` - - `always: optional object { read_only, tool_names }` + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - A filter object to specify which tools are allowed. + - `id: string` - - `read_only: optional boolean` + The unique ID of the file search 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. + - `queries: array of string` - - `tool_names: optional array of string` + The queries used to search for files. - List of allowed tool names. + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `never: optional object { read_only, tool_names }` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - A filter object to specify which tools are allowed. + - `"in_progress"` - - `read_only: optional boolean` + - `"searching"` - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `"completed"` - - `tool_names: optional array of string` + - `"incomplete"` - List of allowed tool names. + - `"failed"` - - `McpToolApprovalSetting = "always" or "never"` + - `type: "file_search_call"` - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + The type of the file search tool call. Always `file_search_call`. - - `"always"` + - `"file_search_call"` - - `"never"` + - `agent: optional object { agent_name }` - - `server_description: optional string` + The agent that produced this item. - Optional description of the MCP server, used to provide more context. + - `agent_name: string` - - `server_url: optional string` + The canonical name of the agent that produced this item. - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `tunnel_id: optional string` + The results of the file search 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. + - `attributes: optional map[string or number or boolean]` - - `CodeInterpreter object { container, type, allowed_callers }` + 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 tool that runs Python code to help generate a response to a prompt. + - `string` - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `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. + - `boolean` - - `string` + - `file_id: optional string` - The container ID. + The unique ID of the file. - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + - `filename: optional string` - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + The name of the file. - - `type: "auto"` + - `score: optional number` - Always `auto`. + The relevance score of the file - a value between 0 and 1. - - `"auto"` + - `text: optional string` - - `file_ids: optional array of string` + The text that was retrieved from the file. - An optional list of uploaded files to make available to your code. + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - The memory limit for the code interpreter container. + - `id: string` - - `"1g"` + The unique ID of the computer call. - - `"4g"` + - `call_id: string` - - `"16g"` + An identifier used when responding to the tool call with output. - - `"64g"` + - `pending_safety_checks: array of object { id, code, message }` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + The pending safety checks for the computer call. - Network access policy for the container. + - `id: string` - - `BetaContainerNetworkPolicyDisabled object { type }` + The ID of the pending safety check. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `code: optional string` - - `type: "code_interpreter"` + The type of the pending safety check. - The type of the code interpreter tool. Always `code_interpreter`. + - `message: optional string` - - `"code_interpreter"` + Details about the pending safety check. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `status: "in_progress" or "completed" or "incomplete"` - The tool invocation context(s). + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"direct"` + - `"in_progress"` - - `"programmatic"` + - `"completed"` - - `ProgrammaticToolCalling object { type }` + - `"incomplete"` - - `type: "programmatic_tool_calling"` + - `type: "computer_call"` - The type of the tool. Always `programmatic_tool_calling`. + The type of the computer call. Always `computer_call`. - - `"programmatic_tool_calling"` + - `"computer_call"` - - `ImageGeneration object { type, action, background, 9 more }` + - `action: optional BetaComputerAction` - A tool that generates images using the GPT image models. + A click action. - - `type: "image_generation"` + - `Click object { button, type, x, 2 more }` - The type of the image generation tool. Always `image_generation`. + A click action. - - `"image_generation"` + - `button: "left" or "right" or "wheel" or 2 more` - - `action: optional "generate" or "edit" or "auto"` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `"left"` - - `"generate"` + - `"right"` - - `"edit"` + - `"wheel"` - - `"auto"` + - `"back"` - - `background: optional "transparent" or "opaque" or "auto"` + - `"forward"` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + - `type: "click"` - - `"transparent"` + Specifies the event type. For a click action, this property is always `click`. - - `"opaque"` + - `"click"` - - `"auto"` + - `x: number` - - `input_fidelity: optional "high" or "low"` + The x-coordinate where the click occurred. - 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`. + - `y: number` - - `"high"` + The y-coordinate where the click occurred. - - `"low"` + - `keys: optional array of string` - - `input_image_mask: optional object { file_id, image_url }` + The keys being held while clicking. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `DoubleClick object { keys, type, x, y }` - - `file_id: optional string` + A double click action. - File ID for the mask image. + - `keys: array of string` - - `image_url: optional string` + The keys being held while double-clicking. - Base64-encoded mask image. + - `type: "double_click"` - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + Specifies the event type. For a double click action, this property is always set to `double_click`. - The image generation model to use. Default: `gpt-image-1`. + - `"double_click"` - - `string` + - `x: number` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + The x-coordinate where the double click occurred. - The image generation model to use. Default: `gpt-image-1`. + - `y: number` - - `"gpt-image-1"` + The y-coordinate where the double click occurred. - - `"gpt-image-1-mini"` + - `Drag object { path, type, keys }` - - `"gpt-image-1.5"` + A drag action. - - `moderation: optional "auto" or "low"` + - `path: array of object { x, y }` - Moderation level for the generated image. Default: `auto`. + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `"auto"` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - - `"low"` + - `x: number` - - `output_compression: optional number` + The x-coordinate. - Compression level for the output image. Default: 100. + - `y: number` - - `output_format: optional "png" or "webp" or "jpeg"` + The y-coordinate. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `type: "drag"` - - `"png"` + Specifies the event type. For a drag action, this property is always set to `drag`. - - `"webp"` + - `"drag"` - - `"jpeg"` + - `keys: optional array of string` - - `partial_images: optional number` + The keys being held while dragging the mouse. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `Keypress object { keys, type }` - - `quality: optional "low" or "medium" or "high" or "auto"` + A collection of keypresses the model would like to perform. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `keys: array of string` - - `"low"` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `"medium"` + - `type: "keypress"` - - `"high"` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `"auto"` + - `"keypress"` - - `size: optional string or "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. - - `string` + - `type: "move"` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + Specifies the event type. For a move action, this property is always set to `move`. - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + - `"move"` - - `"1024x1024"` + - `x: number` - - `"1024x1536"` + The x-coordinate to move to. - - `"1536x1024"` + - `y: number` - - `"auto"` + The y-coordinate to move to. - - `LocalShell object { type }` + - `keys: optional array of string` - A tool that allows the model to execute shell commands in a local environment. + The keys being held while moving the mouse. - - `type: "local_shell"` + - `Screenshot object { type }` - The type of the local shell tool. Always `local_shell`. + A screenshot action. - - `"local_shell"` + - `type: "screenshot"` - - `Shell object { type, allowed_callers, environment }` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - A tool that allows the model to execute shell commands. + - `"screenshot"` - - `type: "shell"` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - The type of the shell tool. Always `shell`. + A scroll action. - - `"shell"` + - `scroll_x: number` - - `allowed_callers: optional array of "direct" or "programmatic"` + The horizontal scroll distance. - The tool invocation context(s). + - `scroll_y: number` - - `"direct"` + The vertical scroll distance. - - `"programmatic"` + - `type: "scroll"` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `"scroll"` - - `BetaLocalEnvironment object { type, skills }` + - `x: number` - - `BetaContainerReference object { container_id, type }` + The x-coordinate where the scroll occurred. - - `Custom object { name, type, allowed_callers, 3 more }` + - `y: number` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + The y-coordinate where the scroll occurred. - - `name: string` + - `keys: optional array of string` - The name of the custom tool, used to identify it in tool calls. + The keys being held while scrolling. - - `type: "custom"` + - `Type object { text, type }` - The type of the custom tool. Always `custom`. + An action to type in text. - - `"custom"` + - `text: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The text to type. - The tool invocation context(s). + - `type: "type"` - - `"direct"` + Specifies the event type. For a type action, this property is always set to `type`. - - `"programmatic"` + - `"type"` - - `defer_loading: optional boolean` + - `Wait object { type }` - Whether this tool should be deferred and discovered via tool search. + A wait action. - - `description: optional string` + - `type: "wait"` - Optional description of the custom tool, used to provide more context. + Specifies the event type. For a wait action, this property is always set to `wait`. - - `format: optional object { type } or object { definition, syntax, type }` + - `"wait"` - The input format for the custom tool. Default is unconstrained text. + - `actions: optional BetaComputerActionList` - - `Text object { type }` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - Unconstrained free-form text. + - `Click object { button, type, x, 2 more }` - - `type: "text"` + A click action. - Unconstrained text format. Always `text`. + - `DoubleClick object { keys, type, x, y }` - - `"text"` + A double click action. - - `Grammar object { definition, syntax, type }` + - `Drag object { path, type, keys }` - A grammar defined by the user. + A drag action. - - `definition: string` + - `Keypress object { keys, type }` - The grammar definition. + A collection of keypresses the model would like to perform. - - `syntax: "lark" or "regex"` + - `Move object { type, x, y, keys }` - The syntax of the grammar definition. One of `lark` or `regex`. + A mouse move action. - - `"lark"` + - `Screenshot object { type }` - - `"regex"` + A screenshot action. - - `type: "grammar"` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - Grammar format. Always `grammar`. + A scroll action. - - `"grammar"` + - `Type object { text, type }` - - `Namespace object { description, name, tools, type }` + An action to type in text. - Groups function/custom tools under a shared namespace. + - `Wait object { type }` - - `description: string` + A wait action. - A description of the namespace shown to the model. + - `agent: optional object { agent_name }` - - `name: string` + The agent that produced this item. - The namespace name used in tool calls (for example, `crm`). + - `agent_name: string` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + The canonical name of the agent that produced this item. - The function/custom tools available inside this namespace. + - `ComputerCallOutput object { id, call_id, output, 5 more }` - - `Function object { name, type, allowed_callers, 5 more }` + - `id: string` - - `name: string` + The unique ID of the computer call tool output. - - `type: "function"` + - `call_id: string` - - `"function"` + The ID of the computer tool call that produced the output. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `output: BetaResponseComputerToolCallOutputScreenshot` - The tool invocation context(s). + A computer screenshot image used with the computer use tool. - - `"direct"` + - `type: "computer_screenshot"` - - `"programmatic"` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `defer_loading: optional boolean` + - `"computer_screenshot"` - Whether this function should be deferred and discovered via tool search. + - `file_id: optional string` - - `description: optional string` + The identifier of an uploaded file that contains the screenshot. - - `output_schema: optional map[unknown]` + - `image_url: optional string` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + The URL of the screenshot image. - - `parameters: optional unknown` + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - - `strict: optional boolean` + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - 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) + - `"failed"` - - `name: string` + - `"in_progress"` - The name of the custom tool, used to identify it in tool calls. + - `type: "computer_call_output"` - - `type: "custom"` + The type of the computer tool call output. Always `computer_call_output`. - The type of the custom tool. Always `custom`. + - `"computer_call_output"` - - `"custom"` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `allowed_callers: optional array of "direct" or "programmatic"` + The safety checks reported by the API that have been acknowledged by the + developer. - 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 tool should be deferred and discovered via tool search. + - `message: optional string` - - `description: optional string` + Details about the pending safety check. - Optional description of the custom tool, used to provide more context. + - `agent: optional object { agent_name }` - - `format: optional object { type } or object { definition, syntax, type }` + The agent that produced this item. - The input format for the custom tool. Default is unconstrained text. + - `agent_name: string` - - `Text object { type }` + The canonical name of the agent that produced this item. - Unconstrained free-form text. + - `created_by: optional string` - - `type: "text"` + The identifier of the actor that created the item. - Unconstrained text format. Always `text`. + - `WebSearchCall object { id, action, status, 2 more }` - - `"text"` + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - - `Grammar object { definition, syntax, type }` + - `id: string` - A grammar defined by the user. + The unique ID of the web search tool call. - - `definition: string` + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - The grammar definition. + 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). - - `syntax: "lark" or "regex"` + - `Search object { type, queries, query, sources }` - The syntax of the grammar definition. One of `lark` or `regex`. + Action type "search" - Performs a web search query. - - `"lark"` + - `type: "search"` - - `"regex"` + The action type. - - `type: "grammar"` + - `"search"` - Grammar format. Always `grammar`. + - `queries: optional array of string` - - `"grammar"` + The search queries. - - `type: "namespace"` + - `query: optional string` - The type of the tool. Always `namespace`. + The search query. - - `"namespace"` + - `sources: optional array of object { type, url }` - - `ToolSearch object { type, description, execution, parameters }` + The sources used in the search. - Hosted or BYOT tool search configuration for deferred tools. + - `type: "url"` - - `type: "tool_search"` + The type of source. Always `url`. - The type of the tool. Always `tool_search`. + - `"url"` - - `"tool_search"` + - `url: string` - - `description: optional string` + The URL of the source. - Description shown to the model for a client-executed tool search tool. + - `OpenPage object { type, url }` - - `execution: optional "server" or "client"` + Action type "open_page" - Opens a specific URL from search results. - Whether tool search is executed by the server or by the client. + - `type: "open_page"` - - `"server"` + The action type. - - `"client"` + - `"open_page"` - - `parameters: optional unknown` + - `url: optional string` - Parameter schema for a client-executed tool search tool. + The URL opened by the model. - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + - `FindInPage object { pattern, type, url }` - 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). + Action type "find_in_page": Searches for a pattern within a loaded page. - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + - `pattern: string` - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + The pattern or text to search for within the page. - - `"web_search_preview"` + - `type: "find_in_page"` - - `"web_search_preview_2025_03_11"` + The action type. - - `search_content_types: optional array of "text" or "image"` + - `"find_in_page"` - - `"text"` + - `url: string` - - `"image"` + The URL of the page searched for the pattern. - - `search_context_size: optional "low" or "medium" or "high"` + - `status: "in_progress" or "searching" or "completed" or "failed"` - 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 web search tool call. - - `"low"` + - `"in_progress"` - - `"medium"` + - `"searching"` - - `"high"` + - `"completed"` - - `user_location: optional object { type, city, country, 2 more }` + - `"failed"` - The user's location. + - `type: "web_search_call"` - - `type: "approximate"` + The type of the web search tool call. Always `web_search_call`. - The type of location approximation. Always `approximate`. + - `"web_search_call"` - - `"approximate"` + - `agent: optional object { agent_name }` - - `city: optional string` + The agent that produced this item. - Free text input for the city of the user, e.g. `San Francisco`. + - `agent_name: string` - - `country: optional string` + The canonical name of the agent that produced this item. - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `FunctionCall object { id, arguments, call_id, 7 more }` - - `region: optional string` + - `id: string` - Free text input for the region of the user, e.g. `California`. + The unique ID of the function tool call. - - `timezone: optional string` + - `arguments: string` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + A JSON string of the arguments to pass to the function. - - `ApplyPatch object { type, allowed_callers }` + - `call_id: string` - Allows the assistant to create, delete, or update files using unified diffs. + The unique ID of the function tool call generated by the model. - - `type: "apply_patch"` + - `name: string` - The type of the tool. Always `apply_patch`. + The name of the function to run. - - `"apply_patch"` + - `status: "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`. Populated when items are returned via API. - The tool invocation context(s). + - `"in_progress"` - - `"direct"` + - `"completed"` - - `"programmatic"` + - `"incomplete"` - - `type: "additional_tools"` + - `type: "function_call"` - The type of the item. Always `additional_tools`. + The type of the function tool call. Always `function_call`. - - `"additional_tools"` + - `"function_call"` - `agent: optional object { agent_name }` @@ -207379,66 +208270,70 @@ curl https://api.openai.com/v1/responses/resp_abc123/input_items \ The canonical name of the agent that produced this item. - - `Reasoning object { id, summary, type, 4 more }` + - `caller: optional object { type } or object { caller_id, type }` - 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 execution context that produced this tool call. - - `id: string` + - `Direct object { type }` - The unique identifier of the reasoning content. + - `type: "direct"` - - `summary: array of object { text, type }` + - `"direct"` - Reasoning summary content. + - `Program object { caller_id, type }` - - `text: string` + - `caller_id: string` - A summary of the reasoning output from the model so far. + The call ID of the program item that produced this tool call. - - `type: "summary_text"` + - `type: "program"` - The type of the object. Always `summary_text`. + - `"program"` - - `"summary_text"` + - `created_by: optional string` - - `type: "reasoning"` + The identifier of the actor that created the item. - The type of the object. Always `reasoning`. + - `namespace: optional string` - - `"reasoning"` + The namespace of the function to run. - - `agent: optional object { agent_name }` + - `FunctionCallOutput object { id, call_id, output, 5 more }` - The agent that produced this item. + - `id: string` - - `agent_name: string` + The unique ID of the function call tool output. - The canonical name of the agent that produced this item. + - `call_id: string` - - `content: optional array of object { text, type }` + The unique ID of the function tool call generated by the model. - Reasoning text content. + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `text: string` + The output from the function call generated by your code. + Can be a string or an list of output content. - The reasoning text from the model. + - `StringOutput = string` - - `type: "reasoning_text"` + A string of the output of the function call. - The type of the reasoning text. Always `reasoning_text`. + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `"reasoning_text"` + Text, image, or file output of the function call. - - `encrypted_content: optional string` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - 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. + A text input to the model. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + + An image input to the model. Learn about [image inputs](/docs/guides/vision). + + - `BetaResponseInputFile 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. @@ -207449,210 +208344,227 @@ curl https://api.openai.com/v1/responses/resp_abc123/input_items \ - `"incomplete"` - - `Program object { id, call_id, code, 3 more }` + - `type: "function_call_output"` - - `id: string` + The type of the function tool call output. Always `function_call_output`. - The unique ID of the program item. + - `"function_call_output"` - - `call_id: string` + - `agent: optional object { agent_name }` - The stable call ID of the program item. + The agent that produced this item. - - `code: string` + - `agent_name: string` - The JavaScript source executed by programmatic tool calling. + The canonical name of the agent that produced this item. - - `fingerprint: string` + - `caller: optional object { type } or object { caller_id, type }` - Opaque program replay fingerprint that must be round-tripped. + 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 type of the item. Always `program`. + The caller type. Always `program`. - `"program"` - - `agent: optional object { agent_name }` + - `created_by: optional string` - The agent that produced this item. + The identifier of the actor that created the item. - - `agent_name: string` + - `AgentMessage object { id, author, content, 3 more }` - The canonical name of the agent that produced this item. + - `id: string` - - `ProgramOutput object { id, call_id, result, 3 more }` + The unique ID of the agent message. - - `id: string` + - `author: string` - The unique ID of the program output item. + The sending agent identity. - - `call_id: string` + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - The call ID of the program item. + Encrypted content sent between agents. - - `result: string` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - The result produced by the program item. + A text input to the model. - - `status: "completed" or "incomplete"` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - The terminal status of the program output item. + A text output from the model. - - `"completed"` + - `Text object { text, type }` - - `"incomplete"` + A text content. - - `type: "program_output"` + - `text: string` - The type of the item. Always `program_output`. + - `type: "text"` - - `"program_output"` + - `"text"` - - `agent: optional object { agent_name }` + - `SummaryText object { text, type }` - The agent that produced this item. + A summary text from the model. - - `agent_name: string` + - `text: string` - The canonical name of the agent that produced this item. + A summary of the reasoning output from the model so far. - - `Compaction object { id, encrypted_content, type, 2 more }` + - `type: "summary_text"` - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + The type of the object. Always `summary_text`. - - `id: string` + - `"summary_text"` - The unique ID of the compaction item. + - `ReasoningText object { text, type }` - - `encrypted_content: string` + Reasoning text from the model. - The encrypted content that was produced by compaction. + - `text: string` - - `type: "compaction"` + The reasoning text from the model. - The type of the item. Always `compaction`. + - `type: "reasoning_text"` - - `"compaction"` + The type of the reasoning text. Always `reasoning_text`. - - `agent: optional object { agent_name }` + - `"reasoning_text"` - The agent that produced this item. + - `BetaResponseOutputRefusal object { refusal, type }` - - `agent_name: string` + A refusal from the model. - The canonical name of the agent that produced this item. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `created_by: optional string` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - The identifier of the actor that created the item. + - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` - - `ImageGenerationCall object { id, result, status, 2 more }` + A screenshot of a computer. - An image generation request made by the model. + - `detail: "low" or "high" or "auto" or "original"` - - `id: string` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - The unique ID of the image generation call. + - `"low"` - - `result: string` + - `"high"` - The generated image encoded in base64. + - `"auto"` - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `"original"` - The status of the image generation call. + - `file_id: string` - - `"in_progress"` + The identifier of an uploaded file that contains the screenshot. - - `"completed"` + - `image_url: string` - - `"generating"` + The URL of the screenshot image. - - `"failed"` + - `type: "computer_screenshot"` - - `type: "image_generation_call"` + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - The type of the image generation call. Always `image_generation_call`. + - `"computer_screenshot"` - - `"image_generation_call"` + - `prompt_cache_breakpoint: optional object { mode }` - - `agent: optional object { agent_name }` + 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 agent that produced this item. + - `mode: "explicit"` - - `agent_name: string` + The breakpoint mode. Always `explicit`. - The canonical name of the agent that produced this item. + - `"explicit"` - - `CodeInterpreterCall object { id, code, container_id, 4 more }` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - A tool call to run code. + A file input to the model. - - `id: string` + - `EncryptedContent object { encrypted_content, type }` - The unique ID of the code interpreter tool call. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `code: string` + - `encrypted_content: string` - The code to run, or null if not available. + Opaque encrypted content. - - `container_id: string` + - `type: "encrypted_content"` - The ID of the container used to run the code. + The type of the input item. Always `encrypted_content`. - - `outputs: array of object { logs, type } or object { type, url }` + - `"encrypted_content"` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `recipient: string` - - `Logs object { logs, type }` + The destination agent identity. - The logs output from the code interpreter. + - `type: "agent_message"` - - `logs: string` + The type of the item. Always `agent_message`. - The logs output from the code interpreter. + - `"agent_message"` - - `type: "logs"` + - `agent: optional object { agent_name }` - The type of the output. Always `logs`. + The agent that produced this item. - - `"logs"` + - `agent_name: string` - - `Image object { type, url }` + The canonical name of the agent that produced this item. - The image output from the code interpreter. + - `MultiAgentCall object { id, action, arguments, 3 more }` - - `type: "image"` + - `id: string` - The type of the output. Always `image`. + The unique ID of the multi-agent call item. - - `"image"` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `url: string` + The multi-agent action to execute. - The URL of the image output from the code interpreter. + - `"spawn_agent"` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `"interrupt_agent"` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + - `"list_agents"` - - `"in_progress"` + - `"send_message"` - - `"completed"` + - `"followup_task"` - - `"incomplete"` + - `"wait_agent"` - - `"interpreting"` + - `arguments: string` - - `"failed"` + The JSON string of arguments generated for the action. - - `type: "code_interpreter_call"` + - `call_id: string` - The type of the code interpreter tool call. Always `code_interpreter_call`. + The unique ID linking this call to its output. - - `"code_interpreter_call"` + - `type: "multi_agent_call"` + + The type of the multi-agent call. Always `multi_agent_call`. + + - `"multi_agent_call"` - `agent: optional object { agent_name }` @@ -207662,63 +208574,55 @@ curl https://api.openai.com/v1/responses/resp_abc123/input_items \ The canonical name of the agent that produced this item. - - `LocalShellCall object { id, action, call_id, 3 more }` - - A tool call to run a command on the local shell. + - `MultiAgentCallOutput object { id, action, call_id, 3 more }` - `id: string` - The unique ID of the local shell call. - - - `action: object { command, env, type, 3 more }` - - Execute a shell command on the server. - - - `command: array of string` + The unique ID of the multi-agent call output item. - The command to run. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `env: map[string]` + The multi-agent action that produced this result. - Environment variables to set for the command. + - `"spawn_agent"` - - `type: "exec"` + - `"interrupt_agent"` - The type of the local shell action. Always `exec`. + - `"list_agents"` - - `"exec"` + - `"send_message"` - - `timeout_ms: optional number` + - `"followup_task"` - Optional timeout in milliseconds for the command. + - `"wait_agent"` - - `user: optional string` + - `call_id: string` - Optional user to run the command as. + The unique ID of the multi-agent call. - - `working_directory: optional string` + - `output: array of BetaResponseOutputText` - Optional working directory to run the command in. + Text output returned by the multi-agent action. - - `call_id: 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 }` - The unique ID of the local shell tool call generated by the model. + The annotations of the text output. - - `status: "in_progress" or "completed" or "incomplete"` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - The status of the local shell call. + - `text: string` - - `"in_progress"` + The text output from the model. - - `"completed"` + - `type: "output_text"` - - `"incomplete"` + The type of the output text. Always `output_text`. - - `type: "local_shell_call"` + - `type: "multi_agent_call_output"` - The type of the local shell call. Always `local_shell_call`. + The type of the multi-agent result. Always `multi_agent_call_output`. - - `"local_shell_call"` + - `"multi_agent_call_output"` - `agent: optional object { agent_name }` @@ -207728,35 +208632,31 @@ curl https://api.openai.com/v1/responses/resp_abc123/input_items \ The canonical name of the agent that produced this item. - - `LocalShellCallOutput object { id, output, type, 2 more }` - - The output of a local shell tool call. + - `ToolSearchCall object { id, arguments, call_id, 5 more }` - `id: string` - The unique ID of the local shell tool call generated by the model. - - - `output: string` + The unique ID of the tool search call item. - A JSON string of the output of the local shell tool call. + - `arguments: unknown` - - `type: "local_shell_call_output"` + Arguments used for the tool search call. - The type of the local shell tool call output. Always `local_shell_call_output`. + - `call_id: string` - - `"local_shell_call_output"` + The unique ID of the tool search call generated by the model. - - `agent: optional object { agent_name }` + - `execution: "server" or "client"` - The agent that produced this item. + Whether tool search was executed by the server or by the client. - - `agent_name: string` + - `"server"` - The canonical name of the agent that produced this item. + - `"client"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `status: "in_progress" or "completed" or "incomplete"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The status of the tool search call item that was recorded. - `"in_progress"` @@ -207764,61 +208664,45 @@ curl https://api.openai.com/v1/responses/resp_abc123/input_items \ - `"incomplete"` - - `ShellCall object { id, action, call_id, 6 more }` - - 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. + - `type: "tool_search_call"` - - `timeout_ms: number` + The type of the item. Always `tool_search_call`. - Optional timeout in milliseconds for the commands. + - `"tool_search_call"` - - `call_id: string` + - `agent: optional object { agent_name }` - The unique ID of the shell tool call generated by the model. + The agent that produced this item. - - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` + - `agent_name: string` - Represents the use of a local environment to perform shell actions. + The canonical name of the agent that produced this item. - - `BetaResponseLocalEnvironment object { type }` + - `created_by: optional string` - Represents the use of a local environment to perform shell actions. + The identifier of the actor that created the item. - - `type: "local"` + - `ToolSearchOutput object { id, call_id, execution, 5 more }` - The environment type. Always `local`. + - `id: string` - - `"local"` + The unique ID of the tool search output item. - - `BetaResponseContainerReference object { container_id, type }` + - `call_id: string` - Represents a container created with /v1/containers. + The unique ID of the tool search call generated by the model. - - `container_id: string` + - `execution: "server" or "client"` - - `type: "container_reference"` + Whether tool search was executed by the server or by the client. - The environment type. Always `container_reference`. + - `"server"` - - `"container_reference"` + - `"client"` - `status: "in_progress" or "completed" or "incomplete"` - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + The status of the tool search output item that was recorded. - `"in_progress"` @@ -207826,1114 +208710,1154 @@ curl https://api.openai.com/v1/responses/resp_abc123/input_items \ - `"incomplete"` - - `type: "shell_call"` + - `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 type of the item. Always `shell_call`. + The loaded tool definitions returned by tool search. - - `"shell_call"` + - `Function object { name, parameters, strict, 5 more }` - - `agent: optional object { agent_name }` + 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 agent that produced this item. + - `name: string` - - `agent_name: string` + The name of the function to call. - The canonical name of the agent that produced this item. + - `parameters: map[unknown]` - - `caller: optional object { type } or object { caller_id, type }` + A JSON schema object describing the parameters of the function. - The execution context that produced this tool call. + - `strict: boolean` - - `Direct object { type }` + Whether strict parameter validation is enforced for this function tool. - - `type: "direct"` + - `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"` - - `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` - - `"program"` + A description of the function. Used by the model to determine whether or not to call the function. - - `created_by: optional string` + - `output_schema: optional map[unknown]` - The ID of the entity that created this tool call. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - The output of a shell tool call that was emitted. + A tool that searches for relevant content from uploaded files. Learn more about the [file search tool](https://platform.openai.com/docs/guides/tools-file-search). - - `id: string` + - `type: "file_search"` - The unique ID of the shell call output. Populated when this item is returned via API. + The type of the file search tool. Always `file_search`. - - `call_id: string` + - `"file_search"` - The unique ID of the shell tool call generated by the model. + - `vector_store_ids: array of string` - - `max_output_length: number` + The IDs of the vector stores to search. - The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. + - `filters: optional object { key, type, value } or object { filters, type }` - - `output: array of object { outcome, stderr, stdout, created_by }` + A filter to apply. - An array of shell call output contents + - `ComparisonFilter object { key, type, value }` - - `outcome: object { type } or object { exit_code, type }` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. + - `key: string` - - `Timeout object { type }` + The key to compare against the value. - Indicates that the shell call exceeded its configured time limit. + - `type: "eq" or "ne" or "gt" or 5 more` - - `type: "timeout"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The outcome type. Always `timeout`. + - `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 - - `"timeout"` + - `"eq"` - - `Exit object { exit_code, type }` + - `"ne"` - Indicates that the shell commands finished and returned an exit code. + - `"gt"` - - `exit_code: number` + - `"gte"` - Exit code from the shell process. + - `"lt"` - - `type: "exit"` + - `"lte"` - The outcome type. Always `exit`. + - `"in"` - - `"exit"` + - `"nin"` - - `stderr: string` + - `value: string or number or boolean or array of string or number` - The standard error output that was captured. + The value to compare against the attribute key; supports string, number, or boolean types. - - `stdout: string` + - `string` - The standard output that was captured. + - `number` - - `created_by: optional string` + - `boolean` - The identifier of the actor that created the item. + - `array of string or number` - - `status: "in_progress" or "completed" or "incomplete"` + - `string` - The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. + - `number` - - `"in_progress"` + - `CompoundFilter object { filters, type }` - - `"completed"` + Combine multiple filters using `and` or `or`. - - `"incomplete"` + - `filters: array of object { key, type, value } or unknown` - - `type: "shell_call_output"` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - The type of the shell call output. Always `shell_call_output`. + - `ComparisonFilter object { key, type, value }` - - `"shell_call_output"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `agent: optional object { agent_name }` + - `key: string` - The agent that produced this item. + The key to compare against the value. - - `agent_name: string` + - `type: "eq" or "ne" or "gt" or 5 more` - The canonical name of the agent that produced this item. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `caller: optional object { type } or object { caller_id, type }` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - The execution context that produced this tool call. + - `"eq"` - - `Direct object { type }` + - `"ne"` - - `type: "direct"` + - `"gt"` - - `"direct"` + - `"gte"` - - `Program object { caller_id, type }` + - `"lt"` - - `caller_id: string` + - `"lte"` - The call ID of the program item that produced this tool call. + - `"in"` - - `type: "program"` + - `"nin"` - - `"program"` + - `value: string or number or boolean or array of string or number` - - `created_by: optional string` + The value to compare against the attribute key; supports string, number, or boolean types. - The identifier of the actor that created the item. + - `string` - - `ApplyPatchCall object { id, call_id, operation, 5 more }` + - `number` - A tool call that applies file diffs by creating, deleting, or updating files. + - `boolean` - - `id: string` + - `array of string or number` - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `string` - - `call_id: string` + - `number` - The unique ID of the apply patch tool call generated by the model. + - `unknown` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + - `type: "and" or "or"` - One of the create_file, delete_file, or update_file operations applied via apply_patch. + Type of operation: `and` or `or`. - - `CreateFile object { diff, path, type }` + - `"and"` - Instruction describing how to create a file via the apply_patch tool. + - `"or"` - - `diff: string` + - `max_num_results: optional number` - Diff to apply. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `path: string` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - Path of the file to create. + Ranking options for search. - - `type: "create_file"` + - `hybrid_search: optional object { embedding_weight, text_weight }` - Create a new file with the provided diff. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `"create_file"` + - `embedding_weight: number` - - `DeleteFile object { path, type }` + The weight of the embedding in the reciprocal ranking fusion. - Instruction describing how to delete a file via the apply_patch tool. + - `text_weight: number` - - `path: string` + The weight of the text in the reciprocal ranking fusion. - Path of the file to delete. + - `ranker: optional "auto" or "default-2024-11-15"` - - `type: "delete_file"` + The ranker to use for the file search. - Delete the specified file. + - `"auto"` - - `"delete_file"` + - `"default-2024-11-15"` - - `UpdateFile object { diff, path, type }` + - `score_threshold: optional number` - Instruction describing how to update a file via the apply_patch tool. + 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. - - `diff: string` + - `Computer object { type }` - Diff to apply. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `path: string` + - `type: "computer"` - Path of the file to update. + The type of the computer tool. Always `computer`. - - `type: "update_file"` + - `"computer"` - Update an existing file with the provided diff. + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `"update_file"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `status: "in_progress" or "completed"` + - `display_height: number` - The status of the apply patch tool call. One of `in_progress` or `completed`. + The height of the computer display. - - `"in_progress"` + - `display_width: number` - - `"completed"` + The width of the computer display. - - `type: "apply_patch_call"` + - `environment: "windows" or "mac" or "linux" or 2 more` - The type of the item. Always `apply_patch_call`. + The type of computer environment to control. - - `"apply_patch_call"` + - `"windows"` - - `agent: optional object { agent_name }` + - `"mac"` - The agent that produced this item. + - `"linux"` - - `agent_name: string` + - `"ubuntu"` - The canonical name of the agent that produced this item. + - `"browser"` - - `caller: optional object { type } or object { caller_id, type }` + - `type: "computer_use_preview"` - The execution context that produced this tool call. + The type of the computer use tool. Always `computer_use_preview`. - - `Direct object { type }` + - `"computer_use_preview"` - - `type: "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"` - - `"program"` + - `filters: optional object { allowed_domains }` - - `created_by: optional string` + Filters for the search. - The ID of the entity that created this tool call. + - `allowed_domains: optional array of string` - - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - The output emitted by an apply patch tool call. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `id: string` + - `search_context_size: optional "low" or "medium" or "high"` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + 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 unique ID of the apply patch tool call generated by the model. + - `"medium"` - - `status: "completed" or "failed"` + - `"high"` - The status of the apply patch tool call output. One of `completed` or `failed`. + - `user_location: optional object { city, country, region, 2 more }` - - `"completed"` + The approximate location of the user. - - `"failed"` + - `city: optional string` - - `type: "apply_patch_call_output"` + Free text input for the city of the user, e.g. `San Francisco`. - The type of the item. Always `apply_patch_call_output`. + - `country: optional string` - - `"apply_patch_call_output"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `agent: optional object { agent_name }` + - `region: optional string` - The agent that produced this item. + Free text input for the region of the user, e.g. `California`. - - `agent_name: string` + - `timezone: optional string` - The canonical name of the agent that produced this item. + 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 }` + - `type: optional "approximate"` - The execution context that produced this tool call. + The type of location approximation. Always `approximate`. - - `Direct object { type }` + - `"approximate"` - - `type: "direct"` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `"direct"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `Program object { caller_id, type }` + - `server_label: string` - - `caller_id: string` + A label for this MCP server, used to identify it in tool calls. - The call ID of the program item that produced this tool call. + - `type: "mcp"` - - `type: "program"` + The type of the MCP tool. Always `mcp`. - - `"program"` + - `"mcp"` - - `created_by: optional string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The ID of the entity that created this tool call output. + The tool invocation context(s). - - `output: optional string` + - `"direct"` - Optional textual output returned by the apply patch tool. + - `"programmatic"` - - `McpListTools object { id, server_label, tools, 3 more }` + - `allowed_tools: optional array of string or object { read_only, tool_names }` - A list of tools available on an MCP server. + List of allowed tool names or a filter object. - - `id: string` + - `McpAllowedTools = array of string` - The unique ID of the list. + A string array of allowed tool names - - `server_label: string` + - `McpToolFilter object { read_only, tool_names }` - The label of the MCP server. + A filter object to specify which tools are allowed. - - `tools: array of object { input_schema, name, annotations, description }` + - `read_only: optional boolean` - The tools available on the server. + 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. - - `input_schema: unknown` + - `tool_names: optional array of string` - The JSON schema describing the tool's input. + List of allowed tool names. - - `name: string` + - `authorization: optional string` - The name of the tool. + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - - `annotations: optional unknown` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - Additional annotations about the tool. + 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). - - `description: optional string` + Currently supported `connector_id` values are: - The description of the tool. + - 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: "mcp_list_tools"` + - `"connector_dropbox"` - The type of the item. Always `mcp_list_tools`. + - `"connector_gmail"` - - `"mcp_list_tools"` + - `"connector_googlecalendar"` - - `agent: optional object { agent_name }` + - `"connector_googledrive"` - The agent that produced this item. + - `"connector_microsoftteams"` - - `agent_name: string` + - `"connector_outlookcalendar"` - The canonical name of the agent that produced this item. + - `"connector_outlookemail"` - - `error: optional string` + - `"connector_sharepoint"` - Error message if the server could not list tools. + - `defer_loading: optional boolean` - - `McpApprovalRequest object { id, arguments, name, 3 more }` + Whether this MCP tool is deferred and discovered via tool search. - A request for human approval of a tool invocation. + - `headers: optional map[string]` - - `id: string` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The unique ID of the approval request. + - `require_approval: optional object { always, never } or "always" or "never"` - - `arguments: string` + Specify which of the MCP server's tools require approval. - A JSON string of arguments for the tool. + - `McpToolApprovalFilter object { always, never }` - - `name: 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 name of the tool to run. + - `always: optional object { read_only, tool_names }` - - `server_label: string` + A filter object to specify which tools are allowed. - The label of the MCP server making the request. + - `read_only: optional boolean` - - `type: "mcp_approval_request"` + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - The type of the item. Always `mcp_approval_request`. + - `tool_names: optional array of string` - - `"mcp_approval_request"` + List of allowed tool names. - - `agent: optional object { agent_name }` + - `never: optional object { read_only, tool_names }` - The agent that produced this item. + A filter object to specify which tools are allowed. - - `agent_name: string` + - `read_only: optional boolean` - The canonical name of the agent that produced this item. + 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. - - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` + - `tool_names: optional array of string` - A response to an MCP approval request. + List of allowed tool names. - - `id: string` + - `McpToolApprovalSetting = "always" or "never"` - The unique ID of the approval response + 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. - - `approval_request_id: string` + - `"always"` - The ID of the approval request being answered. + - `"never"` - - `approve: boolean` + - `server_description: optional string` - Whether the request was approved. + Optional description of the MCP server, used to provide more context. - - `type: "mcp_approval_response"` + - `server_url: optional string` - The type of the item. Always `mcp_approval_response`. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `"mcp_approval_response"` + - `tunnel_id: optional string` - - `agent: optional object { agent_name }` + 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 agent that produced this item. + - `CodeInterpreter object { container, type, allowed_callers }` - - `agent_name: string` + A tool that runs Python code to help generate a response to a prompt. - The canonical name of the agent that produced this item. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `reason: optional string` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - Optional reason for the decision. + - `string` - - `McpCall object { id, arguments, name, 7 more }` + The container ID. - An invocation of a tool on an MCP server. + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `id: string` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The unique ID of the tool call. + - `type: "auto"` - - `arguments: string` + Always `auto`. - A JSON string of the arguments passed to the tool. + - `"auto"` - - `name: string` + - `file_ids: optional array of string` - The name of the tool that was run. + An optional list of uploaded files to make available to your code. - - `server_label: string` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The label of the MCP server running the tool. + The memory limit for the code interpreter container. - - `type: "mcp_call"` + - `"1g"` - The type of the item. Always `mcp_call`. + - `"4g"` - - `"mcp_call"` + - `"16g"` - - `agent: optional object { agent_name }` + - `"64g"` - The agent that produced this item. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `agent_name: string` + Network access policy for the container. - The canonical name of the agent that produced this item. + - `BetaContainerNetworkPolicyDisabled object { type }` - - `approval_request_id: optional string` + - `type: "disabled"` - 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. + Disable outbound network access. Always `disabled`. - - `error: optional string` + - `"disabled"` - The error from the tool call, if any. + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `output: optional string` + - `allowed_domains: array of string` - The output from the tool call. + A list of allowed domains when type is `allowlist`. - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `type: "allowlist"` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + Allow outbound network access only to specified domains. Always `allowlist`. - - `"in_progress"` + - `"allowlist"` - - `"completed"` + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - - `"incomplete"` + Optional domain-scoped secrets for allowlisted domains. - - `"calling"` + - `domain: string` - - `"failed"` + The domain associated with the secret. - - `CustomToolCall object { id, call_id, input, 7 more }` + - `name: string` - - `id: string` + The name of the secret to inject for the domain. - The unique ID of the custom tool call item. + - `value: string` - - `call_id: string` + The secret value to inject for the domain. - An identifier used to map this custom tool call to a tool call output. + - `type: "code_interpreter"` - - `input: string` + The type of the code interpreter tool. Always `code_interpreter`. - The input for the custom tool call generated by the model. + - `"code_interpreter"` - - `name: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The name of the custom tool being called. + The tool invocation context(s). - - `status: "in_progress" or "completed" or "incomplete"` + - `"direct"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"programmatic"` - - `"in_progress"` + - `ProgrammaticToolCalling object { type }` - - `"completed"` + - `type: "programmatic_tool_calling"` - - `"incomplete"` + The type of the tool. Always `programmatic_tool_calling`. - - `type: "custom_tool_call"` + - `"programmatic_tool_calling"` - The type of the custom tool call. Always `custom_tool_call`. + - `ImageGeneration object { type, action, background, 9 more }` - - `"custom_tool_call"` + A tool that generates images using the GPT image models. - - `agent: optional object { agent_name }` + - `type: "image_generation"` - The agent that produced this item. + The type of the image generation tool. Always `image_generation`. - - `agent_name: string` + - `"image_generation"` - The canonical name of the agent that produced this item. + - `action: optional "generate" or "edit" or "auto"` - - `caller: optional object { type } or object { caller_id, type }` + Whether to generate a new image or edit an existing image. Default: `auto`. - The execution context that produced this tool call. + - `"generate"` - - `Direct object { type }` + - `"edit"` - - `type: "direct"` + - `"auto"` - - `"direct"` + - `background: optional "transparent" or "opaque" or "auto"` - - `Program object { caller_id, type }` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `caller_id: string` + - `"transparent"` - The call ID of the program item that produced this tool call. + - `"opaque"` - - `type: "program"` + - `"auto"` - - `"program"` + - `input_fidelity: optional "high" or "low"` - - `created_by: optional string` + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - The identifier of the actor that created the item. + - `"high"` - - `namespace: optional string` + - `"low"` - The namespace of the custom tool being called. + - `input_image_mask: optional object { file_id, image_url }` - - `CustomToolCallOutput object { id, call_id, output, 5 more }` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `id: string` + - `file_id: optional string` - The unique ID of the custom tool call output item. + File ID for the mask image. - - `call_id: string` + - `image_url: optional string` - The call ID, used to map this custom tool call output to a custom tool call. + Base64-encoded mask image. - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + The image generation model to use. Default: `gpt-image-1`. - - `StringOutput = string` + - `string` - A string of the output of the custom tool call. + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + The image generation model to use. Default: `gpt-image-1`. - Text, image, or file output of the custom tool call. + - `"gpt-image-1"` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `"gpt-image-1-mini"` - A text input to the model. + - `"gpt-image-1.5"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `moderation: optional "auto" or "low"` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + Moderation level for the generated image. Default: `auto`. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `"auto"` - A file input to the model. + - `"low"` - - `status: "in_progress" or "completed" or "incomplete"` + - `output_compression: optional number` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + Compression level for the output image. Default: 100. - - `"in_progress"` + - `output_format: optional "png" or "webp" or "jpeg"` - - `"completed"` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `"incomplete"` + - `"png"` - - `type: "custom_tool_call_output"` + - `"webp"` - The type of the custom tool call output. Always `custom_tool_call_output`. + - `"jpeg"` - - `"custom_tool_call_output"` + - `partial_images: optional number` - - `agent: optional object { agent_name }` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The agent that produced this item. + - `quality: optional "low" or "medium" or "high" or "auto"` - - `agent_name: string` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - The canonical name of the agent that produced this item. + - `"low"` - - `caller: optional object { type } or object { caller_id, type }` + - `"medium"` - The execution context that produced this tool call. + - `"high"` - - `Direct object { type }` + - `"auto"` - - `type: "direct"` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - The caller type. Always `direct`. + 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`. - - `"direct"` + - `string` - - `Program object { caller_id, type }` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `caller_id: string` + The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. - The call ID of the program item that produced this tool call. + - `"1024x1024"` - - `type: "program"` + - `"1024x1536"` - The caller type. Always `program`. + - `"1536x1024"` - - `"program"` + - `"auto"` - - `created_by: optional string` + - `LocalShell object { type }` - The identifier of the actor that created the item. + A tool that allows the model to execute shell commands in a local environment. - - `first_id: string` + - `type: "local_shell"` - The ID of the first item in the list. + The type of the local shell tool. Always `local_shell`. - - `has_more: boolean` + - `"local_shell"` - Whether there are more items available. + - `Shell object { type, allowed_callers, environment }` - - `last_id: string` + A tool that allows the model to execute shell commands. - The ID of the last item in the list. + - `type: "shell"` - - `object: "list"` + The type of the shell tool. Always `shell`. - The type of object returned, must be `list`. + - `"shell"` - - `"list"` + - `allowed_callers: optional array of "direct" or "programmatic"` -# Input Tokens + The tool invocation context(s). -## Get input token counts + - `"direct"` -**post** `/responses/input_tokens?beta=true` + - `"programmatic"` -Returns input token counts of the request. + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` -Returns an object with `object` set to `response.input_tokens` and an `input_tokens` count. + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` -### Header Parameters + - `type: "container_auto"` -- `"openai-beta": optional array of "responses_multi_agent=v1"` + Automatically creates a container for this request - - `"responses_multi_agent=v1"` + - `"container_auto"` -### Body Parameters + - `file_ids: optional array of string` -- `conversation: optional string or BetaResponseConversationParam` + An optional list of uploaded files to make available to your code. - 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. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `ConversationID = string` + The memory limit for the container. - The unique ID of the conversation. + - `"1g"` - - `BetaResponseConversationParam object { id }` + - `"4g"` - The conversation that this response belongs to. + - `"16g"` - - `id: string` + - `"64g"` - The unique ID of the conversation. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` -- `input: optional string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + Network access policy for the container. - Text, image, or file inputs to the model, used to generate a response + - `BetaContainerNetworkPolicyDisabled object { type }` - - `string` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - A text input to the model, equivalent to a text input with the `user` role. + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - - `array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` + An optional list of skills referenced by id or inline data. - A list of one or many input items to the model, containing different content types. + - `BetaSkillReference object { skill_id, type, version }` - - `BetaEasyInputMessage object { content, role, phase, type }` + - `skill_id: 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 ID of the referenced skill. - - `content: string or BetaResponseInputMessageContentList` + - `type: "skill_reference"` - Text, image, or audio input to the model, used to generate a response. - Can also contain previous assistant responses. + References a skill created with the /v1/skills endpoint. - - `TextInput = string` + - `"skill_reference"` - A text input to the model. + - `version: optional string` - - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - A list of one or many input items to the model, containing different content - types. + - `BetaInlineSkill object { description, name, source, type }` - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `description: string` - A text input to the model. + The description of the skill. - - `text: string` + - `name: string` - The text input to the model. + The name of the skill. - - `type: "input_text"` + - `source: BetaInlineSkillSource` - The type of the input item. Always `input_text`. + Inline skill payload - - `"input_text"` + - `data: string` - - `prompt_cache_breakpoint: optional object { mode }` + Base64-encoded skill zip bundle. - 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. + - `media_type: "application/zip"` - - `mode: "explicit"` + The media type of the inline skill payload. Must be `application/zip`. - The breakpoint mode. Always `explicit`. + - `"application/zip"` - - `"explicit"` + - `type: "base64"` - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + The type of the inline skill source. Must be `base64`. - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `"base64"` - - `detail: "low" or "high" or "auto" or "original"` + - `type: "inline"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + Defines an inline skill for this request. - - `"low"` + - `"inline"` - - `"high"` + - `BetaLocalEnvironment object { type, skills }` - - `"auto"` + - `type: "local"` - - `"original"` + Use a local computer environment. - - `type: "input_image"` + - `"local"` - The type of the input item. Always `input_image`. + - `skills: optional array of BetaLocalSkill` - - `"input_image"` + An optional list of skills. - - `file_id: optional string` + - `description: string` - The ID of the file to be sent to the model. + The description of the skill. - - `image_url: optional string` + - `name: 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 name of the skill. - - `prompt_cache_breakpoint: optional object { mode }` + - `path: 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 path to the directory containing the skill. - - `mode: "explicit"` + - `BetaContainerReference object { container_id, type }` - The breakpoint mode. Always `explicit`. + - `container_id: string` - - `"explicit"` + The ID of the referenced container. - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + - `type: "container_reference"` - A file input to the model. + References a container created with the /v1/containers endpoint - - `type: "input_file"` + - `"container_reference"` - The type of the input item. Always `input_file`. + - `Custom object { name, type, allowed_callers, 3 more }` - - `"input_file"` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `detail: optional "auto" or "low" or "high"` + - `name: string` - 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 name of the custom tool, used to identify it in tool calls. - - `"auto"` + - `type: "custom"` - - `"low"` + The type of the custom tool. Always `custom`. - - `"high"` + - `"custom"` - - `file_data: optional string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The content of the file to be sent to the model. + The tool invocation context(s). - - `file_id: optional string` + - `"direct"` - The ID of the file to be sent to the model. + - `"programmatic"` - - `file_url: optional string` + - `defer_loading: optional boolean` - The URL of the file to be sent to the model. + Whether this tool should be deferred and discovered via tool search. - - `filename: optional string` + - `description: optional string` - The name of the file to be sent to the model. + Optional description of the custom tool, used to provide more context. - - `prompt_cache_breakpoint: optional object { mode }` + - `format: optional object { type } or object { definition, syntax, 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. + The input format for the custom tool. Default is unconstrained text. - - `mode: "explicit"` + - `Text object { type }` - The breakpoint mode. Always `explicit`. + Unconstrained free-form text. - - `"explicit"` + - `type: "text"` - - `role: "user" or "assistant" or "system" or "developer"` + Unconstrained text format. Always `text`. - The role of the message input. One of `user`, `assistant`, `system`, or - `developer`. + - `"text"` - - `"user"` + - `Grammar object { definition, syntax, type }` - - `"assistant"` + A grammar defined by the user. - - `"system"` + - `definition: string` - - `"developer"` + The grammar definition. - - `phase: optional "commentary" or "final_answer"` + - `syntax: "lark" or "regex"` - 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 syntax of the grammar definition. One of `lark` or `regex`. - - `"commentary"` + - `"lark"` - - `"final_answer"` + - `"regex"` - - `type: optional "message"` + - `type: "grammar"` - The type of the message input. Always `message`. + Grammar format. Always `grammar`. - - `"message"` + - `"grammar"` - - `Message object { content, role, agent, 2 more }` + - `Namespace object { description, name, tools, 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. + Groups function/custom tools under a shared namespace. - - `content: BetaResponseInputMessageContentList` + - `description: string` - A list of one or many input items to the model, containing different content - types. + A description of the namespace shown to the model. - - `role: "user" or "system" or "developer"` + - `name: string` - The role of the message input. One of `user`, `system`, or `developer`. + The namespace name used in tool calls (for example, `crm`). - - `"user"` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `"system"` + The function/custom tools available inside this namespace. - - `"developer"` + - `Function object { name, type, allowed_callers, 5 more }` - - `agent: optional object { agent_name }` + - `name: string` - The agent that produced this item. + - `type: "function"` - - `agent_name: string` + - `"function"` - The canonical name of the agent that produced this item. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `status: optional "in_progress" or "completed" or "incomplete"` + The tool invocation context(s). - The status of item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"direct"` - - `"in_progress"` + - `"programmatic"` - - `"completed"` + - `defer_loading: optional boolean` - - `"incomplete"` + Whether this function should be deferred and discovered via tool search. - - `type: optional "message"` + - `description: optional string` - The type of the message input. Always set to `message`. + - `output_schema: optional map[unknown]` - - `"message"` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `BetaResponseOutputMessage object { id, content, role, 4 more }` + - `parameters: optional unknown` - An output message from the model. + - `strict: optional boolean` - - `id: string` + 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) - The unique ID of the output message. + - `name: string` - - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` + The name of the custom tool, used to identify it in tool calls. - The content of the output message. + - `type: "custom"` - - `BetaResponseOutputText object { annotations, logprobs, text, type }` + The type of the custom tool. Always `custom`. - A text output from the model. + - `"custom"` - - `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 tool should be deferred and discovered via tool search. - - `filename: string` + - `description: optional string` - The filename of the file cited. + Optional description of the custom tool, used to provide more context. - - `index: number` + - `format: optional object { type } or object { definition, syntax, type }` - The index of the file in the list of files. + The input format for the custom tool. Default is unconstrained text. - - `type: "file_citation"` + - `Text object { type }` - The type of the file citation. Always `file_citation`. + Unconstrained free-form text. - - `"file_citation"` + - `type: "text"` - - `URLCitation object { end_index, start_index, title, 2 more }` + Unconstrained text format. Always `text`. - A citation for a web resource used to generate a model response. + - `"text"` - - `end_index: number` + - `Grammar object { definition, syntax, type }` - The index of the last character of the URL citation in the message. + A grammar defined by the user. - - `start_index: number` + - `definition: string` - The index of the first character of the URL citation in the message. + The grammar definition. - - `title: string` + - `syntax: "lark" or "regex"` - The title of the web resource. + The syntax of the grammar definition. One of `lark` or `regex`. - - `type: "url_citation"` + - `"lark"` - The type of the URL citation. Always `url_citation`. + - `"regex"` - - `"url_citation"` + - `type: "grammar"` - - `url: string` + Grammar format. Always `grammar`. - The URL of the web resource. + - `"grammar"` - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + - `type: "namespace"` - A citation for a container file used to generate a model response. + The type of the tool. Always `namespace`. - - `container_id: string` + - `"namespace"` - The ID of the container file. + - `ToolSearch object { type, description, execution, parameters }` - - `end_index: number` + Hosted or BYOT tool search configuration for deferred tools. - The index of the last character of the container file citation in the message. + - `type: "tool_search"` - - `file_id: string` + The type of the tool. Always `tool_search`. - The ID of the file. + - `"tool_search"` - - `filename: string` + - `description: optional string` - The filename of the container file cited. + Description shown to the model for a client-executed tool search tool. - - `start_index: number` + - `execution: optional "server" or "client"` - The index of the first character of the container file citation in the message. + Whether tool search is executed by the server or by the client. - - `type: "container_file_citation"` + - `"server"` - The type of the container file citation. Always `container_file_citation`. + - `"client"` - - `"container_file_citation"` + - `parameters: optional unknown` - - `FilePath object { file_id, index, type }` + Parameter schema for a client-executed tool search tool. - A path to a file. + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `file_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 file. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `index: number` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The index of the file in the list of files. + - `"web_search_preview"` - - `type: "file_path"` + - `"web_search_preview_2025_03_11"` - The type of the file path. Always `file_path`. + - `search_content_types: optional array of "text" or "image"` - - `"file_path"` + - `"text"` - - `logprobs: array of object { token, bytes, logprob, top_logprobs }` + - `"image"` - - `token: string` + - `search_context_size: optional "low" or "medium" or "high"` - - `bytes: array of number` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - - `logprob: number` + - `"low"` - - `top_logprobs: array of object { token, bytes, logprob }` + - `"medium"` - - `token: string` + - `"high"` - - `bytes: array of number` + - `user_location: optional object { type, city, country, 2 more }` - - `logprob: number` + The user's location. - - `text: string` + - `type: "approximate"` - The text output from the model. + The type of location approximation. Always `approximate`. - - `type: "output_text"` + - `"approximate"` - 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`. - - `BetaResponseOutputRefusal 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"` + - `ApplyPatch object { type, allowed_callers }` - - `role: "assistant"` + Allows the assistant to create, delete, or update files using unified diffs. - The role of the output message. Always `assistant`. + - `type: "apply_patch"` - - `"assistant"` + The type of the tool. Always `apply_patch`. - - `status: "in_progress" or "completed" or "incomplete"` + - `"apply_patch"` - The status of the message input. One of `in_progress`, `completed`, or - `incomplete`. Populated when input items are returned via API. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"in_progress"` + The tool invocation context(s). - - `"completed"` + - `"direct"` - - `"incomplete"` + - `"programmatic"` - - `type: "message"` + - `type: "tool_search_output"` - The type of the output message. Always `message`. + The type of the item. Always `tool_search_output`. - - `"message"` + - `"tool_search_output"` - `agent: optional object { agent_name }` @@ -208943,1030 +209867,1073 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok The canonical name of the agent that produced this item. - - `phase: optional "commentary" or "final_answer"` + - `created_by: optional string` - Labels an `assistant` message as intermediate commentary (`commentary`) or the final answer (`final_answer`). - For models like `gpt-5.3-codex` and beyond, when sending follow-up requests, preserve and resend - phase on all assistant messages — dropping it can degrade performance. Not used for user messages. + The identifier of the actor that created the item. - - `"commentary"` + - `AdditionalTools object { id, role, tools, 2 more }` - - `"final_answer"` + - `id: string` - - `FileSearchCall object { id, queries, status, 3 more }` + The unique ID of the additional tools item. - The results of a file search tool call. See the - [file search guide](/docs/guides/tools-file-search) for more information. + - `role: "unknown" or "user" or "assistant" or 5 more` - - `id: string` + The role that provided the additional tools. - The unique ID of the file search tool call. + - `"unknown"` - - `queries: array of string` + - `"user"` - The queries used to search for files. + - `"assistant"` - - `status: "in_progress" or "searching" or "completed" or 2 more` + - `"system"` - The status of the file search tool call. One of `in_progress`, - `searching`, `incomplete` or `failed`, + - `"critic"` - - `"in_progress"` + - `"discriminator"` - - `"searching"` + - `"developer"` - - `"completed"` + - `"tool"` - - `"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` - - `"failed"` + The additional tool definitions made available at this item. - - `type: "file_search_call"` + - `Function object { name, parameters, strict, 5 more }` - The type of the file search tool call. Always `file_search_call`. + 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_search_call"` + - `name: string` - - `agent: optional object { agent_name }` + The name of the function to call. - The agent that produced this item. + - `parameters: map[unknown]` - - `agent_name: string` + A JSON schema object describing the parameters of the function. - The canonical name of the agent that produced this item. + - `strict: boolean` - - `results: optional array of object { attributes, file_id, filename, 2 more }` + Whether strict parameter validation is enforced for this function tool. - The results of the file search tool call. + - `type: "function"` - - `attributes: optional map[string or number or boolean]` + The type of the function tool. Always `function`. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. Keys are strings - with a maximum length of 64 characters. Values are strings with a maximum - length of 512 characters, booleans, or numbers. + - `"function"` - - `string` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `number` + The tool invocation context(s). - - `boolean` + - `"direct"` - - `file_id: optional string` + - `"programmatic"` - The unique ID of the file. + - `defer_loading: optional boolean` - - `filename: optional string` + Whether this function is deferred and loaded via tool search. - The name of the file. + - `description: optional string` - - `score: optional number` + A description of the function. Used by the model to determine whether or not to call the function. - The relevance score of the file - a value between 0 and 1. + - `output_schema: optional map[unknown]` - - `text: optional string` + A JSON schema object describing the JSON value encoded in string outputs for this function. - The text that was retrieved from the file. + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `ComputerCall object { id, call_id, pending_safety_checks, 5 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). - A tool call to a computer use tool. See the - [computer use guide](/docs/guides/tools-computer-use) for more information. + - `type: "file_search"` - - `id: string` + The type of the file search tool. Always `file_search`. - The unique ID of the computer call. + - `"file_search"` - - `call_id: string` + - `vector_store_ids: array of string` - An identifier used when responding to the tool call with output. + The IDs of the vector stores to search. - - `pending_safety_checks: array of object { id, code, message }` + - `filters: optional object { key, type, value } or object { filters, type }` - The pending safety checks for the computer call. + A filter to apply. - - `id: string` + - `ComparisonFilter object { key, type, value }` - The ID of the pending safety check. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `code: optional string` + - `key: string` - The type of the pending safety check. + The key to compare against the value. - - `message: optional string` + - `type: "eq" or "ne" or "gt" or 5 more` - Details about the pending safety check. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `status: "in_progress" or "completed" or "incomplete"` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + - `"eq"` - - `"in_progress"` + - `"ne"` - - `"completed"` + - `"gt"` - - `"incomplete"` + - `"gte"` - - `type: "computer_call"` + - `"lt"` - The type of the computer call. Always `computer_call`. + - `"lte"` - - `"computer_call"` + - `"in"` - - `action: optional BetaComputerAction` + - `"nin"` - A click action. + - `value: string or number or boolean or array of string or number` - - `Click object { button, type, x, 2 more }` + The value to compare against the attribute key; supports string, number, or boolean types. - A click action. + - `string` - - `button: "left" or "right" or "wheel" or 2 more` + - `number` - Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. + - `boolean` - - `"left"` + - `array of string or number` - - `"right"` + - `string` - - `"wheel"` + - `number` - - `"back"` + - `CompoundFilter object { filters, type }` - - `"forward"` + Combine multiple filters using `and` or `or`. - - `type: "click"` + - `filters: array of object { key, type, value } or unknown` - Specifies the event type. For a click action, this property is always `click`. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `"click"` + - `ComparisonFilter object { key, type, value }` - - `x: number` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The x-coordinate where the click occurred. + - `key: string` - - `y: number` + The key to compare against the value. - The y-coordinate where the click occurred. + - `type: "eq" or "ne" or "gt" or 5 more` - - `keys: optional array of string` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The keys being held while clicking. + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `DoubleClick object { keys, type, x, y }` + - `"eq"` - A double click action. + - `"ne"` - - `keys: array of string` + - `"gt"` - The keys being held while double-clicking. + - `"gte"` - - `type: "double_click"` + - `"lt"` - Specifies the event type. For a double click action, this property is always set to `double_click`. + - `"lte"` - - `"double_click"` + - `"in"` - - `x: number` + - `"nin"` - The x-coordinate where the double click occurred. + - `value: string or number or boolean or array of string or number` - - `y: number` + The value to compare against the attribute key; supports string, number, or boolean types. - The y-coordinate where the double click occurred. + - `string` - - `Drag object { path, type, keys }` + - `number` - A drag action. + - `boolean` - - `path: array of object { x, y }` + - `array of string or number` - An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg + - `string` - ``` - [ - { x: 100, y: 200 }, - { x: 200, y: 300 } - ] - ``` + - `number` - - `x: number` + - `unknown` - The x-coordinate. + - `type: "and" or "or"` - - `y: number` + Type of operation: `and` or `or`. - The y-coordinate. + - `"and"` - - `type: "drag"` + - `"or"` - Specifies the event type. For a drag action, this property is always set to `drag`. + - `max_num_results: optional number` - - `"drag"` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `keys: optional array of string` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - The keys being held while dragging the mouse. + Ranking options for search. - - `Keypress object { keys, type }` + - `hybrid_search: optional object { embedding_weight, text_weight }` - A collection of keypresses the model would like to perform. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `keys: array of string` + - `embedding_weight: number` - The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. + The weight of the embedding in the reciprocal ranking fusion. - - `type: "keypress"` + - `text_weight: number` - Specifies the event type. For a keypress action, this property is always set to `keypress`. + The weight of the text in the reciprocal ranking fusion. - - `"keypress"` + - `ranker: optional "auto" or "default-2024-11-15"` - - `Move object { type, x, y, keys }` + The ranker to use for the file search. - A mouse move action. + - `"auto"` - - `type: "move"` + - `"default-2024-11-15"` - Specifies the event type. For a move action, this property is always set to `move`. + - `score_threshold: optional number` - - `"move"` + 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. - - `x: number` + - `Computer object { type }` - The x-coordinate to move to. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `y: number` + - `type: "computer"` - The y-coordinate to move to. + The type of the computer tool. Always `computer`. - - `keys: optional array of string` + - `"computer"` - The keys being held while moving the mouse. + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `Screenshot object { type }` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - A screenshot action. + - `display_height: number` - - `type: "screenshot"` + The height of the computer display. - Specifies the event type. For a screenshot action, this property is always set to `screenshot`. + - `display_width: number` - - `"screenshot"` + The width of the computer display. - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `environment: "windows" or "mac" or "linux" or 2 more` - A scroll action. + The type of computer environment to control. - - `scroll_x: number` + - `"windows"` - The horizontal scroll distance. + - `"mac"` - - `scroll_y: number` + - `"linux"` - The vertical scroll distance. + - `"ubuntu"` - - `type: "scroll"` + - `"browser"` - Specifies the event type. For a scroll action, this property is always set to `scroll`. + - `type: "computer_use_preview"` - - `"scroll"` + The type of the computer use tool. Always `computer_use_preview`. - - `x: number` + - `"computer_use_preview"` - The x-coordinate where the scroll occurred. + - `WebSearch object { type, filters, search_context_size, user_location }` - - `y: number` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - The y-coordinate where the scroll occurred. + - `type: "web_search" or "web_search_2025_08_26"` - - `keys: optional array of string` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - The keys being held while scrolling. + - `"web_search"` - - `Type object { text, type }` + - `"web_search_2025_08_26"` - An action to type in text. + - `filters: optional object { allowed_domains }` - - `text: string` + Filters for the search. - The text to type. + - `allowed_domains: optional array of string` - - `type: "type"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - Specifies the event type. For a type action, this property is always set to `type`. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `"type"` + - `search_context_size: optional "low" or "medium" or "high"` - - `Wait object { 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. - A wait action. + - `"low"` - - `type: "wait"` + - `"medium"` - Specifies the event type. For a wait action, this property is always set to `wait`. + - `"high"` - - `"wait"` + - `user_location: optional object { city, country, region, 2 more }` - - `actions: optional BetaComputerActionList` + The approximate location of the user. - Flattened batched actions for `computer_use`. Each action includes an - `type` discriminator and action-specific fields. + - `city: optional string` - - `Click object { button, type, x, 2 more }` + Free text input for the city of the user, e.g. `San Francisco`. - A click action. + - `country: optional string` - - `DoubleClick object { keys, type, x, y }` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - A double click action. + - `region: optional string` - - `Drag object { path, type, keys }` + Free text input for the region of the user, e.g. `California`. - A drag action. + - `timezone: optional string` - - `Keypress object { keys, type }` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - A collection of keypresses the model would like to perform. + - `type: optional "approximate"` - - `Move object { type, x, y, keys }` + The type of location approximation. Always `approximate`. - A mouse move action. + - `"approximate"` - - `Screenshot object { type }` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - A screenshot action. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `Scroll object { scroll_x, scroll_y, type, 3 more }` + - `server_label: string` - A scroll action. + A label for this MCP server, used to identify it in tool calls. - - `Type object { text, type }` + - `type: "mcp"` - An action to type in text. + The type of the MCP tool. Always `mcp`. - - `Wait object { type }` + - `"mcp"` - A wait action. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `agent: optional object { agent_name }` + The tool invocation context(s). - The agent that produced this item. + - `"direct"` - - `agent_name: string` + - `"programmatic"` - The canonical name of the agent that produced this item. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `ComputerCallOutput object { call_id, output, type, 4 more }` + List of allowed tool names or a filter object. - The output of a computer tool call. + - `McpAllowedTools = array of string` - - `call_id: string` + A string array of allowed tool names - The ID of the computer tool call that produced the output. + - `McpToolFilter object { read_only, tool_names }` - - `output: BetaResponseComputerToolCallOutputScreenshot` + A filter object to specify which tools are allowed. - A computer screenshot image used with the computer use tool. + - `read_only: optional boolean` - - `type: "computer_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. - Specifies the event type. For a computer screenshot, this property is - always set to `computer_screenshot`. + - `tool_names: optional array of string` - - `"computer_screenshot"` + List of allowed tool names. - - `file_id: optional string` + - `authorization: optional string` - The identifier of an uploaded file that contains the screenshot. + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - - `image_url: optional string` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - The URL of the screenshot image. + Identifier for service connectors, like those available in ChatGPT. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. Learn more + about service connectors [here](/docs/guides/tools-remote-mcp#connectors). - - `type: "computer_call_output"` + Currently supported `connector_id` values are: - The type of the computer tool call output. Always `computer_call_output`. + - Dropbox: `connector_dropbox` + - Gmail: `connector_gmail` + - Google Calendar: `connector_googlecalendar` + - Google Drive: `connector_googledrive` + - Microsoft Teams: `connector_microsoftteams` + - Outlook Calendar: `connector_outlookcalendar` + - Outlook Email: `connector_outlookemail` + - SharePoint: `connector_sharepoint` - - `"computer_call_output"` + - `"connector_dropbox"` - - `id: optional string` + - `"connector_gmail"` - The ID of the computer tool call output. + - `"connector_googlecalendar"` - - `acknowledged_safety_checks: optional array of object { id, code, message }` + - `"connector_googledrive"` - The safety checks reported by the API that have been acknowledged by the developer. + - `"connector_microsoftteams"` - - `id: string` + - `"connector_outlookcalendar"` - The ID of the pending safety check. + - `"connector_outlookemail"` - - `code: optional string` + - `"connector_sharepoint"` - The type of the pending safety check. + - `defer_loading: optional boolean` - - `message: optional string` + Whether this MCP tool is deferred and discovered via tool search. - Details about the pending safety check. + - `headers: optional map[string]` - - `agent: optional object { agent_name }` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The agent that produced this item. + - `require_approval: optional object { always, never } or "always" or "never"` - - `agent_name: string` + Specify which of the MCP server's tools require approval. - The canonical name of the agent that produced this item. + - `McpToolApprovalFilter object { always, never }` - - `status: optional "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 message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input 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. - - `WebSearchCall object { id, action, status, 2 more }` + - `tool_names: optional array of string` - The results of a web search tool call. See the - [web search guide](/docs/guides/tools-web-search) for more information. + List of allowed tool names. - - `id: string` + - `never: optional object { read_only, tool_names }` - The unique ID of the web search tool call. + A filter object to specify which tools are allowed. - - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` + - `read_only: optional boolean` - 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). + 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. - - `Search object { type, queries, query, sources }` + - `tool_names: optional array of string` - Action type "search" - Performs a web search query. + List of allowed tool names. - - `type: "search"` + - `McpToolApprovalSetting = "always" or "never"` - The action 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. - - `"search"` + - `"always"` - - `queries: optional array of string` + - `"never"` - The search queries. + - `server_description: optional string` - - `query: optional string` + Optional description of the MCP server, used to provide more context. - The search query. + - `server_url: optional string` - - `sources: optional array of object { type, url }` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - The sources used in the search. + - `tunnel_id: optional string` - - `type: "url"` + 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 type of source. Always `url`. + - `CodeInterpreter object { container, type, allowed_callers }` - - `"url"` + A tool that runs Python code to help generate a response to a prompt. - - `url: string` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - The URL of the source. + 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. - - `OpenPage object { type, url }` + - `string` - Action type "open_page" - Opens a specific URL from search results. + The container ID. - - `type: "open_page"` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - The action type. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `"open_page"` + - `type: "auto"` - - `url: optional string` + Always `auto`. - The URL opened by the model. + - `"auto"` - - `FindInPage object { pattern, type, url }` + - `file_ids: optional array of string` - Action type "find_in_page": Searches for a pattern within a loaded page. + An optional list of uploaded files to make available to your code. - - `pattern: string` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The pattern or text to search for within the page. + The memory limit for the code interpreter container. - - `type: "find_in_page"` + - `"1g"` - The action type. + - `"4g"` - - `"find_in_page"` + - `"16g"` - - `url: string` + - `"64g"` - The URL of the page searched for the pattern. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `status: "in_progress" or "searching" or "completed" or "failed"` + Network access policy for the container. - The status of the web search tool call. + - `BetaContainerNetworkPolicyDisabled object { type }` - - `"in_progress"` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `"searching"` + - `type: "code_interpreter"` - - `"completed"` + The type of the code interpreter tool. Always `code_interpreter`. - - `"failed"` + - `"code_interpreter"` - - `type: "web_search_call"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The type of the web search tool call. Always `web_search_call`. + The tool invocation context(s). - - `"web_search_call"` + - `"direct"` - - `agent: optional object { agent_name }` + - `"programmatic"` - The agent that produced this item. + - `ProgrammaticToolCalling object { type }` - - `agent_name: string` + - `type: "programmatic_tool_calling"` - The canonical name of the agent that produced this item. + The type of the tool. Always `programmatic_tool_calling`. - - `FunctionCall object { arguments, call_id, name, 6 more }` + - `"programmatic_tool_calling"` - A tool call to run a function. See the - [function calling guide](/docs/guides/function-calling) for more information. + - `ImageGeneration object { type, action, background, 9 more }` - - `arguments: string` + A tool that generates images using the GPT image models. - A JSON string of the arguments to pass to the function. + - `type: "image_generation"` - - `call_id: string` + The type of the image generation tool. Always `image_generation`. - The unique ID of the function tool call generated by the model. + - `"image_generation"` - - `name: string` + - `action: optional "generate" or "edit" or "auto"` - The name of the function to run. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `type: "function_call"` + - `"generate"` - The type of the function tool call. Always `function_call`. + - `"edit"` - - `"function_call"` + - `"auto"` - - `id: optional string` + - `background: optional "transparent" or "opaque" or "auto"` - The unique ID of the function tool call. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `agent: optional object { agent_name }` + - `"transparent"` - The agent that produced this item. + - `"opaque"` - - `agent_name: string` + - `"auto"` - The canonical name of the agent that produced this item. + - `input_fidelity: optional "high" or "low"` - - `caller: optional object { type } or object { caller_id, 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`. - The execution context that produced this tool call. + - `"high"` - - `Direct object { type }` + - `"low"` - - `type: "direct"` + - `input_image_mask: optional object { file_id, image_url }` - - `"direct"` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `Program object { caller_id, type }` + - `file_id: optional string` - - `caller_id: string` + File ID for the mask image. - The call ID of the program item that produced this tool call. + - `image_url: optional string` - - `type: "program"` + Base64-encoded mask image. - - `"program"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `namespace: optional string` + The image generation model to use. Default: `gpt-image-1`. - The namespace of the function to run. + - `string` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + The image generation model to use. Default: `gpt-image-1`. - - `"in_progress"` + - `"gpt-image-1"` - - `"completed"` + - `"gpt-image-1-mini"` - - `"incomplete"` + - `"gpt-image-1.5"` - - `FunctionCallOutput object { call_id, output, type, 4 more }` + - `moderation: optional "auto" or "low"` - The output of a function tool call. + Moderation level for the generated image. Default: `auto`. - - `call_id: string` + - `"auto"` - The unique ID of the function tool call generated by the model. + - `"low"` - - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` + - `output_compression: optional number` - Text, image, or file output of the function tool call. + Compression level for the output image. Default: 100. - - `string` + - `output_format: optional "png" or "webp" or "jpeg"` - A JSON string of the output of the function tool call. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` + - `"png"` - An array of content outputs (text, image, file) for the function tool call. + - `"webp"` - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + - `"jpeg"` - A text input to the model. + - `partial_images: optional number` - - `text: string` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - The text input to the model. + - `quality: optional "low" or "medium" or "high" or "auto"` - - `type: "input_text"` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - The type of the input item. Always `input_text`. + - `"low"` - - `"input_text"` + - `"medium"` - - `prompt_cache_breakpoint: optional object { mode }` + - `"high"` - 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. + - `"auto"` - - `mode: "explicit"` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - The breakpoint mode. Always `explicit`. + 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`. - - `"explicit"` + - `string` - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - An image input to the model. Learn about [image inputs](/docs/guides/vision) + 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: "input_image"` + - `"1024x1024"` - The type of the input item. Always `input_image`. + - `"1024x1536"` - - `"input_image"` + - `"1536x1024"` - - `detail: optional "low" or "high" or "auto" or "original"` + - `"auto"` - The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. + - `LocalShell object { type }` - - `"low"` + A tool that allows the model to execute shell commands in a local environment. - - `"high"` + - `type: "local_shell"` - - `"auto"` + The type of the local shell tool. Always `local_shell`. - - `"original"` + - `"local_shell"` - - `file_id: optional string` + - `Shell object { type, allowed_callers, environment }` - The ID of the file to be sent to the model. + A tool that allows the model to execute shell commands. - - `image_url: optional string` + - `type: "shell"` - The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. + The type of the shell tool. Always `shell`. - - `prompt_cache_breakpoint: optional object { mode }` + - `"shell"` - 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. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `mode: "explicit"` + The tool invocation context(s). - The breakpoint mode. Always `explicit`. + - `"direct"` - - `"explicit"` + - `"programmatic"` - - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - A file input to the model. + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `type: "input_file"` + - `BetaLocalEnvironment object { type, skills }` - The type of the input item. Always `input_file`. + - `BetaContainerReference object { container_id, type }` - - `"input_file"` + - `Custom object { name, type, allowed_callers, 3 more }` - - `detail: optional "auto" or "low" or "high"` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-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`. + - `name: string` - - `"auto"` + The name of the custom tool, used to identify it in tool calls. - - `"low"` + - `type: "custom"` - - `"high"` + The type of the custom tool. Always `custom`. - - `file_data: optional string` + - `"custom"` - The base64-encoded data of the file to be sent to the model. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `file_id: optional string` + The tool invocation context(s). - The ID of the file to be sent to the model. + - `"direct"` - - `file_url: optional string` + - `"programmatic"` - The URL of the file to be sent to the model. + - `defer_loading: optional boolean` - - `filename: optional string` + Whether this tool should be deferred and discovered via tool search. - The name of the file to be sent to the model. + - `description: optional string` - - `prompt_cache_breakpoint: optional object { mode }` + Optional description of the custom tool, used to provide more context. - 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. + - `format: optional object { type } or object { definition, syntax, type }` - - `mode: "explicit"` + The input format for the custom tool. Default is unconstrained text. - The breakpoint mode. Always `explicit`. + - `Text object { type }` - - `"explicit"` + Unconstrained free-form text. - - `type: "function_call_output"` + - `type: "text"` - The type of the function tool call output. Always `function_call_output`. + Unconstrained text format. Always `text`. - - `"function_call_output"` + - `"text"` - - `id: optional string` + - `Grammar object { definition, syntax, type }` - The unique ID of the function tool call output. Populated when this item is returned via API. + A grammar defined by the user. - - `agent: optional object { agent_name }` + - `definition: string` - The agent that produced this item. + The grammar definition. - - `agent_name: string` + - `syntax: "lark" or "regex"` - The canonical name of the agent that produced this item. + The syntax of the grammar definition. One of `lark` or `regex`. - - `caller: optional object { type } or object { caller_id, type }` + - `"lark"` - The execution context that produced this tool call. + - `"regex"` - - `Direct object { type }` + - `type: "grammar"` - - `type: "direct"` + Grammar format. Always `grammar`. - The caller type. Always `direct`. + - `"grammar"` - - `"direct"` + - `Namespace object { description, name, tools, type }` - - `Program object { caller_id, type }` + Groups function/custom tools under a shared namespace. - - `caller_id: string` + - `description: string` - The call ID of the program item that produced this tool call. + A description of the namespace shown to the model. - - `type: "program"` + - `name: string` - The caller type. Always `program`. + 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"` - - `"program"` + 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`. Populated when items are returned via API. + - `"programmatic"` - - `"in_progress"` + - `defer_loading: optional boolean` - - `"completed"` + Whether this function should be deferred and discovered via tool search. - - `"incomplete"` + - `description: optional string` - - `AgentMessage object { author, content, recipient, 3 more }` + - `output_schema: optional map[unknown]` - A message routed between agents. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `author: string` + - `parameters: optional unknown` - The sending agent identity. + - `strict: optional boolean` - - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` + 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. - Plaintext, image, or encrypted content sent between agents. + - `Custom object { name, type, allowed_callers, 3 more }` - - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - A text input to the model. + - `name: string` - - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` + The name of the custom tool, used to identify it in tool calls. - An image input to the model. Learn about [image inputs](/docs/guides/vision) + - `type: "custom"` - - `EncryptedContent object { encrypted_content, type }` + The type of the custom tool. Always `custom`. - Opaque encrypted content that Responses API decrypts inside trusted model execution. + - `"custom"` - - `encrypted_content: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - Opaque encrypted content. + The tool invocation context(s). - - `type: "encrypted_content"` + - `"direct"` - The type of the input item. Always `encrypted_content`. + - `"programmatic"` - - `"encrypted_content"` + - `defer_loading: optional boolean` - - `recipient: string` + Whether this tool should be deferred and discovered via tool search. - The destination agent identity. + - `description: optional string` - - `type: "agent_message"` + Optional description of the custom tool, used to provide more context. - The item type. Always `agent_message`. + - `format: optional object { type } or object { definition, syntax, type }` - - `"agent_message"` + The input format for the custom tool. Default is unconstrained text. - - `id: optional string` + - `Text object { type }` - The unique ID of this agent message item. + Unconstrained free-form text. - - `agent: optional object { agent_name }` + - `type: "text"` - The agent that produced this item. + Unconstrained text format. Always `text`. - - `agent_name: string` + - `"text"` - The canonical name of the agent that produced this item. + - `Grammar object { definition, syntax, type }` - - `MultiAgentCall object { action, arguments, call_id, 3 more }` + A grammar defined by the user. - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `definition: string` - The multi-agent action that was executed. + The grammar definition. - - `"spawn_agent"` + - `syntax: "lark" or "regex"` - - `"interrupt_agent"` + The syntax of the grammar definition. One of `lark` or `regex`. - - `"list_agents"` + - `"lark"` - - `"send_message"` + - `"regex"` - - `"followup_task"` + - `type: "grammar"` - - `"wait_agent"` + Grammar format. Always `grammar`. - - `arguments: string` + - `"grammar"` - The action arguments as a JSON string. + - `type: "namespace"` - - `call_id: string` + The type of the tool. Always `namespace`. - The unique ID linking this call to its output. + - `"namespace"` - - `type: "multi_agent_call"` + - `ToolSearch object { type, description, execution, parameters }` - The item type. Always `multi_agent_call`. + Hosted or BYOT tool search configuration for deferred tools. - - `"multi_agent_call"` + - `type: "tool_search"` - - `id: optional string` + The type of the tool. Always `tool_search`. - The unique ID of this multi-agent call. + - `"tool_search"` - - `agent: optional object { agent_name }` + - `description: optional string` - The agent that produced this item. + Description shown to the model for a client-executed tool search tool. - - `agent_name: string` + - `execution: optional "server" or "client"` - The canonical name of the agent that produced this item. + Whether tool search is executed by the server or by the client. - - `MultiAgentCallOutput object { action, call_id, output, 3 more }` + - `"server"` - - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` + - `"client"` - The multi-agent action that produced this result. + - `parameters: optional unknown` - - `"spawn_agent"` + Parameter schema for a client-executed tool search tool. - - `"interrupt_agent"` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `"list_agents"` + 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). - - `"send_message"` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `"followup_task"` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `"wait_agent"` + - `"web_search_preview"` - - `call_id: string` + - `"web_search_preview_2025_03_11"` - The unique ID of the multi-agent call. + - `search_content_types: optional array of "text" or "image"` - - `output: array of object { text, type, annotations }` + - `"text"` - Text output returned by the multi-agent action. + - `"image"` - - `text: string` + - `search_context_size: optional "low" or "medium" or "high"` - The text content. + 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: "output_text"` + - `"low"` - The content type. Always `output_text`. + - `"medium"` - - `"output_text"` + - `"high"` - - `annotations: optional 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 }` + - `user_location: optional object { type, city, country, 2 more }` - Citations associated with the text content. + The user's location. - - `FileCitation object { file_id, filename, index, type }` + - `type: "approximate"` - - `file_id: string` + The type of location approximation. Always `approximate`. - The ID of the file. + - `"approximate"` - - `filename: string` + - `city: optional string` - The filename of the file cited. + Free text input for the city of the user, e.g. `San Francisco`. - - `index: number` + - `country: optional string` - The index of the file in the list of files. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `type: "file_citation"` + - `region: optional string` - The citation type. Always `file_citation`. + Free text input for the region of the user, e.g. `California`. - - `"file_citation"` + - `timezone: optional string` - - `URLCitation object { end_index, start_index, title, 2 more }` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `end_index: number` + - `ApplyPatch object { type, allowed_callers }` - The index of the last character of the citation in the message. + Allows the assistant to create, delete, or update files using unified diffs. - - `start_index: number` + - `type: "apply_patch"` - The index of the first character of the citation in the message. + The type of the tool. Always `apply_patch`. - - `title: string` + - `"apply_patch"` - The title of the cited resource. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "url_citation"` + The tool invocation context(s). - The citation type. Always `url_citation`. + - `"direct"` - - `"url_citation"` + - `"programmatic"` - - `url: string` + - `type: "additional_tools"` - The URL of the cited resource. + The type of the item. Always `additional_tools`. - - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` + - `"additional_tools"` - - `container_id: string` + - `agent: optional object { agent_name }` - The ID of the container. + The agent that produced this item. - - `end_index: number` + - `agent_name: string` - The index of the last character of the citation in the message. + The canonical name of the agent that produced this item. - - `file_id: string` + - `Reasoning object { id, summary, type, 4 more }` - The ID of the container file. + 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). - - `filename: string` + - `id: string` - The filename of the container file cited. + The unique identifier of the reasoning content. - - `start_index: number` + - `summary: array of object { text, type }` - The index of the first character of the citation in the message. + Reasoning summary content. - - `type: "container_file_citation"` + - `text: string` - The citation type. Always `container_file_citation`. + A summary of the reasoning output from the model so far. - - `"container_file_citation"` + - `type: "summary_text"` - - `type: "multi_agent_call_output"` + The type of the object. Always `summary_text`. - The item type. Always `multi_agent_call_output`. + - `"summary_text"` - - `"multi_agent_call_output"` + - `type: "reasoning"` - - `id: optional string` + The type of the object. Always `reasoning`. - The unique ID of this multi-agent call output. + - `"reasoning"` - `agent: optional object { agent_name }` @@ -209976,2270 +210943,2266 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok The canonical name of the agent that produced this item. - - `ToolSearchCall object { arguments, type, id, 4 more }` + - `content: optional array of object { text, type }` - - `arguments: unknown` + Reasoning text content. - The arguments supplied to the tool search call. + - `text: string` - - `type: "tool_search_call"` + The reasoning text from the model. - The item type. Always `tool_search_call`. + - `type: "reasoning_text"` - - `"tool_search_call"` + The type of the reasoning text. Always `reasoning_text`. - - `id: optional string` + - `"reasoning_text"` - The unique ID of this tool search call. + - `encrypted_content: optional string` - - `agent: optional object { agent_name }` + 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 agent that produced this item. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `agent_name: string` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The canonical name of the agent that produced this item. + - `"in_progress"` - - `call_id: optional string` + - `"completed"` - The unique ID of the tool search call generated by the model. + - `"incomplete"` - - `execution: optional "server" or "client"` + - `Program object { id, call_id, code, 3 more }` - Whether tool search was executed by the server or by the client. + - `id: string` - - `"server"` + The unique ID of the program item. - - `"client"` + - `call_id: string` - - `status: optional "in_progress" or "completed" or "incomplete"` + The stable call ID of the program item. - The status of the tool search call. + - `code: string` - - `"in_progress"` + The JavaScript source executed by programmatic tool calling. - - `"completed"` + - `fingerprint: string` - - `"incomplete"` + Opaque program replay fingerprint that must be round-tripped. - - `ToolSearchOutput object { tools, type, id, 4 more }` + - `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` + The type of the item. Always `program`. - The loaded tool definitions returned by the tool search output. + - `"program"` - - `Function object { name, parameters, strict, 5 more }` + - `agent: optional object { agent_name }` - 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 agent that produced this item. - - `name: string` + - `agent_name: string` - The name of the function to call. + The canonical name of the agent that produced this item. - - `parameters: map[unknown]` + - `ProgramOutput object { id, call_id, result, 3 more }` - A JSON schema object describing the parameters of the function. + - `id: string` - - `strict: boolean` + The unique ID of the program output item. - Whether strict parameter validation is enforced for this function tool. + - `call_id: string` - - `type: "function"` + The call ID of the program item. - The type of the function tool. Always `function`. + - `result: string` - - `"function"` + The result produced by the program item. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `status: "completed" or "incomplete"` - The tool invocation context(s). + The terminal status of the program output item. - - `"direct"` + - `"completed"` - - `"programmatic"` + - `"incomplete"` - - `defer_loading: optional boolean` + - `type: "program_output"` - Whether this function is deferred and loaded via tool search. + The type of the item. Always `program_output`. - - `description: optional string` + - `"program_output"` - A description of the function. Used by the model to determine whether or not to call the function. + - `agent: optional object { agent_name }` - - `output_schema: optional map[unknown]` + The agent that produced this item. - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `agent_name: string` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + The canonical name of the agent that produced this item. - 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). + - `Compaction object { id, encrypted_content, type, 2 more }` - - `type: "file_search"` + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - The type of the file search tool. Always `file_search`. + - `id: string` - - `"file_search"` + The unique ID of the compaction item. - - `vector_store_ids: array of string` + - `encrypted_content: string` - The IDs of the vector stores to search. + The encrypted content that was produced by compaction. - - `filters: optional object { key, type, value } or object { filters, type }` + - `type: "compaction"` - A filter to apply. + The type of the item. Always `compaction`. - - `ComparisonFilter object { key, type, value }` + - `"compaction"` - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `agent: optional object { agent_name }` - - `key: string` + The agent that produced this item. - The key to compare against the value. + - `agent_name: string` - - `type: "eq" or "ne" or "gt" or 5 more` + The canonical name of the agent that produced this item. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `created_by: optional string` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + The identifier of the actor that created the item. - - `"eq"` + - `ImageGenerationCall object { id, result, status, 2 more }` - - `"ne"` + An image generation request made by the model. - - `"gt"` + - `id: string` - - `"gte"` + The unique ID of the image generation call. - - `"lt"` + - `result: string` - - `"lte"` + The generated image encoded in base64. - - `"in"` + - `status: "in_progress" or "completed" or "generating" or "failed"` - - `"nin"` + The status of the image generation call. - - `value: string or number or boolean or array of string or number` + - `"in_progress"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `"completed"` - - `string` + - `"generating"` - - `number` + - `"failed"` - - `boolean` + - `type: "image_generation_call"` - - `array of string or number` + The type of the image generation call. Always `image_generation_call`. - - `string` + - `"image_generation_call"` - - `number` + - `agent: optional object { agent_name }` - - `CompoundFilter object { filters, type }` + The agent that produced this item. - Combine multiple filters using `and` or `or`. + - `agent_name: string` - - `filters: array of object { key, type, value } or unknown` + The canonical name of the agent that produced this item. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `CodeInterpreterCall object { id, code, container_id, 4 more }` - - `ComparisonFilter object { key, type, value }` + A tool call to run code. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `id: string` - - `key: string` + The unique ID of the code interpreter tool call. - The key to compare against the value. + - `code: string` - - `type: "eq" or "ne" or "gt" or 5 more` + The code to run, or null if not available. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `container_id: string` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + The ID of the container used to run the code. - - `"eq"` + - `outputs: array of object { logs, type } or object { type, url }` - - `"ne"` + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `"gt"` + - `Logs object { logs, type }` - - `"gte"` + The logs output from the code interpreter. - - `"lt"` + - `logs: string` - - `"lte"` + The logs output from the code interpreter. - - `"in"` + - `type: "logs"` - - `"nin"` + The type of the output. Always `logs`. - - `value: string or number or boolean or array of string or number` + - `"logs"` - The value to compare against the attribute key; supports string, number, or boolean types. + - `Image object { type, url }` - - `string` + The image output from the code interpreter. - - `number` + - `type: "image"` - - `boolean` + The type of the output. Always `image`. - - `array of string or number` + - `"image"` - - `string` + - `url: string` - - `number` + The URL of the image output from the code interpreter. - - `unknown` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - - `type: "and" or "or"` + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - Type of operation: `and` or `or`. + - `"in_progress"` - - `"and"` + - `"completed"` - - `"or"` + - `"incomplete"` - - `max_num_results: optional number` + - `"interpreting"` - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `"failed"` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `type: "code_interpreter_call"` - Ranking options for search. + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `"code_interpreter_call"` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `agent: optional object { agent_name }` - - `embedding_weight: number` + The agent that produced this item. - The weight of the embedding in the reciprocal ranking fusion. + - `agent_name: string` - - `text_weight: number` + The canonical name of the agent that produced this item. - The weight of the text in the reciprocal ranking fusion. + - `LocalShellCall object { id, action, call_id, 3 more }` - - `ranker: optional "auto" or "default-2024-11-15"` + A tool call to run a command on the local shell. - The ranker to use for the file search. + - `id: string` - - `"auto"` + The unique ID of the local shell call. - - `"default-2024-11-15"` + - `action: object { command, env, type, 3 more }` - - `score_threshold: optional number` + Execute a shell command on the server. - 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. + - `command: array of string` - - `Computer object { type }` + The command to run. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `env: map[string]` - - `type: "computer"` + Environment variables to set for the command. - The type of the computer tool. Always `computer`. + - `type: "exec"` - - `"computer"` + The type of the local shell action. Always `exec`. - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `"exec"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `timeout_ms: optional number` - - `display_height: number` + Optional timeout in milliseconds for the command. - The height of the computer display. + - `user: optional string` - - `display_width: number` + Optional user to run the command as. - The width of the computer display. + - `working_directory: optional string` - - `environment: "windows" or "mac" or "linux" or 2 more` + Optional working directory to run the command in. - The type of computer environment to control. + - `call_id: string` - - `"windows"` + The unique ID of the local shell tool call generated by the model. - - `"mac"` + - `status: "in_progress" or "completed" or "incomplete"` - - `"linux"` + The status of the local shell call. - - `"ubuntu"` + - `"in_progress"` - - `"browser"` + - `"completed"` - - `type: "computer_use_preview"` + - `"incomplete"` - The type of the computer use tool. Always `computer_use_preview`. + - `type: "local_shell_call"` - - `"computer_use_preview"` + The type of the local shell call. Always `local_shell_call`. - - `WebSearch object { type, filters, search_context_size, user_location }` + - `"local_shell_call"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-search). + - `agent: optional object { agent_name }` - - `type: "web_search" or "web_search_2025_08_26"` + The agent that produced this item. - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `agent_name: string` - - `"web_search"` + The canonical name of the agent that produced this item. - - `"web_search_2025_08_26"` + - `LocalShellCallOutput object { id, output, type, 2 more }` - - `filters: optional object { allowed_domains }` + The output of a local shell tool call. - Filters for the search. + - `id: string` - - `allowed_domains: optional array of string` + The unique ID of the local shell tool call generated by the model. - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + - `output: string` - Example: `["pubmed.ncbi.nlm.nih.gov"]` + A JSON string of the output of the local shell tool call. - - `search_context_size: optional "low" or "medium" or "high"` + - `type: "local_shell_call_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. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `"low"` + - `"local_shell_call_output"` - - `"medium"` + - `agent: optional object { agent_name }` - - `"high"` + The agent that produced this item. - - `user_location: optional object { city, country, region, 2 more }` + - `agent_name: string` - The approximate location of the user. + The canonical name of the agent that produced this item. - - `city: optional string` + - `status: optional "in_progress" or "completed" or "incomplete"` - Free text input for the city of the user, e.g. `San Francisco`. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `country: optional string` + - `"in_progress"` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + - `"completed"` - - `region: optional string` + - `"incomplete"` - Free text input for the region of the user, e.g. `California`. + - `ShellCall object { id, action, call_id, 6 more }` - - `timezone: optional string` + A tool call that executes one or more shell commands in a managed environment. - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `id: string` - - `type: optional "approximate"` + The unique ID of the shell tool call. Populated when this item is returned via API. - The type of location approximation. Always `approximate`. + - `action: object { commands, max_output_length, timeout_ms }` - - `"approximate"` + The shell commands and limits that describe how to run the tool call. - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `commands: array of string` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + - `max_output_length: number` - - `server_label: string` + Optional maximum number of characters to return from each command. - A label for this MCP server, used to identify it in tool calls. + - `timeout_ms: number` - - `type: "mcp"` + Optional timeout in milliseconds for the commands. - The type of the MCP tool. Always `mcp`. + - `call_id: string` - - `"mcp"` + The unique ID of the shell tool call generated by the model. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - The tool invocation context(s). + Represents the use of a local environment to perform shell actions. - - `"direct"` + - `BetaResponseLocalEnvironment object { type }` - - `"programmatic"` + Represents the use of a local environment to perform shell actions. - - `allowed_tools: optional array of string or object { read_only, tool_names }` + - `type: "local"` - List of allowed tool names or a filter object. + The environment type. Always `local`. - - `McpAllowedTools = array of string` + - `"local"` - A string array of allowed tool names + - `BetaResponseContainerReference object { container_id, type }` - - `McpToolFilter object { read_only, tool_names }` + Represents a container created with /v1/containers. - A filter object to specify which tools are allowed. + - `container_id: string` - - `read_only: optional boolean` + - `type: "container_reference"` - 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 environment type. Always `container_reference`. - - `tool_names: optional array of string` + - `"container_reference"` - List of allowed tool names. + - `status: "in_progress" or "completed" or "incomplete"` - - `authorization: optional string` + The status of the shell call. One of `in_progress`, `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. + - `"in_progress"` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + - `"completed"` - 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). + - `"incomplete"` - 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"` + - `agent: optional object { agent_name }` - - `"connector_googlecalendar"` + The agent that produced this item. - - `"connector_googledrive"` + - `agent_name: string` - - `"connector_microsoftteams"` + The canonical name of the agent that produced this item. - - `"connector_outlookcalendar"` + - `caller: optional object { type } or object { caller_id, type }` - - `"connector_outlookemail"` + The execution context that produced this tool call. - - `"connector_sharepoint"` + - `Direct object { type }` - - `defer_loading: optional boolean` + - `type: "direct"` - Whether this MCP tool is deferred and discovered via tool search. + - `"direct"` - - `headers: optional map[string]` + - `Program object { caller_id, type }` - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `caller_id: string` - - `require_approval: optional object { always, never } or "always" or "never"` + The call ID of the program item that produced this tool call. - Specify which of the MCP server's tools require approval. + - `type: "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. + - `created_by: optional string` - - `always: optional object { read_only, tool_names }` + The ID of the entity that created this tool call. - A filter object to specify which tools are allowed. + - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` - - `read_only: optional boolean` + The output of a shell tool call that was emitted. - Indicates whether or not a tool modifies data or is read-only. If an - MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), - it will match this filter. + - `id: string` - - `tool_names: optional array of string` + The unique ID of the shell call output. Populated when this item is returned via API. - List of allowed tool names. + - `call_id: string` - - `never: optional object { read_only, tool_names }` + The unique ID of the shell tool call generated by the model. - A filter object to specify which tools are allowed. + - `max_output_length: number` - - `read_only: optional boolean` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw 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: array of object { outcome, stderr, stdout, created_by }` - - `tool_names: optional array of string` + An array of shell call output contents - List of allowed tool names. + - `outcome: object { type } or object { exit_code, type }` - - `McpToolApprovalSetting = "always" or "never"` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - 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. + - `Timeout object { type }` - - `"always"` + Indicates that the shell call exceeded its configured time limit. - - `"never"` + - `type: "timeout"` - - `server_description: optional string` + The outcome type. Always `timeout`. - Optional description of the MCP server, used to provide more context. + - `"timeout"` - - `server_url: optional string` + - `Exit object { exit_code, type }` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + Indicates that the shell commands finished and returned an exit code. - - `tunnel_id: optional string` + - `exit_code: number` - 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 code from the shell process. - - `CodeInterpreter object { container, type, allowed_callers }` + - `type: "exit"` - A tool that runs Python code to help generate a response to a prompt. + The outcome type. Always `exit`. - - `container: string or object { type, file_ids, memory_limit, network_policy }` + - `"exit"` - 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. + - `stderr: string` - - `string` + The standard error output that was captured. - The container ID. + - `stdout: string` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + The standard output that was captured. - 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`. + - `status: "in_progress" or "completed" or "incomplete"` - - `"auto"` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - - `file_ids: optional array of string` + - `"in_progress"` - An optional list of uploaded files to make available to your code. + - `"completed"` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `"incomplete"` - The memory limit for the code interpreter container. + - `type: "shell_call_output"` - - `"1g"` + The type of the shell call output. Always `shell_call_output`. - - `"4g"` + - `"shell_call_output"` - - `"16g"` + - `agent: optional object { agent_name }` - - `"64g"` + The agent that produced this item. - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `agent_name: string` - Network access policy for the container. + The canonical name of the agent that produced this item. - - `BetaContainerNetworkPolicyDisabled object { type }` + - `caller: optional object { type } or object { caller_id, type }` - - `type: "disabled"` + The execution context that produced this tool call. - Disable outbound network access. Always `disabled`. + - `Direct object { type }` - - `"disabled"` + - `type: "direct"` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `"direct"` - - `allowed_domains: array of string` + - `Program object { caller_id, type }` - A list of allowed domains when type is `allowlist`. + - `caller_id: string` - - `type: "allowlist"` + The call ID of the program item that produced this tool call. - Allow outbound network access only to specified domains. Always `allowlist`. + - `type: "program"` - - `"allowlist"` + - `"program"` - - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` + - `created_by: optional string` - Optional domain-scoped secrets for allowlisted domains. + The identifier of the actor that created the item. - - `domain: string` + - `ApplyPatchCall object { id, call_id, operation, 5 more }` - The domain associated with the secret. + A tool call that applies file diffs by creating, deleting, or updating files. - - `name: string` + - `id: string` - The name of the secret to inject for the domain. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `value: string` + - `call_id: string` - The secret value to inject for the domain. + The unique ID of the apply patch tool call generated by the model. - - `type: "code_interpreter"` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - The type of the code interpreter tool. Always `code_interpreter`. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `"code_interpreter"` + - `CreateFile object { diff, path, type }` - - `allowed_callers: optional array of "direct" or "programmatic"` + Instruction describing how to create a file via the apply_patch tool. - The tool invocation context(s). + - `diff: string` - - `"direct"` + Diff to apply. - - `"programmatic"` + - `path: string` - - `ProgrammaticToolCalling object { type }` + Path of the file to create. - - `type: "programmatic_tool_calling"` + - `type: "create_file"` - The type of the tool. Always `programmatic_tool_calling`. + Create a new file with the provided diff. - - `"programmatic_tool_calling"` + - `"create_file"` - - `ImageGeneration object { type, action, background, 9 more }` + - `DeleteFile object { path, type }` - A tool that generates images using the GPT image models. + Instruction describing how to delete a file via the apply_patch tool. - - `type: "image_generation"` + - `path: string` - The type of the image generation tool. Always `image_generation`. + Path of the file to delete. - - `"image_generation"` + - `type: "delete_file"` - - `action: optional "generate" or "edit" or "auto"` + Delete the specified file. - Whether to generate a new image or edit an existing image. Default: `auto`. + - `"delete_file"` - - `"generate"` + - `UpdateFile object { diff, path, type }` - - `"edit"` + Instruction describing how to update a file via the apply_patch tool. - - `"auto"` + - `diff: string` - - `background: optional "transparent" or "opaque" or "auto"` + Diff to apply. - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + - `path: string` - - `"transparent"` + Path of the file to update. - - `"opaque"` + - `type: "update_file"` - - `"auto"` + Update an existing file with the provided diff. - - `input_fidelity: optional "high" or "low"` + - `"update_file"` - Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. + - `status: "in_progress" or "completed"` - - `"high"` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `"low"` + - `"in_progress"` - - `input_image_mask: optional object { file_id, image_url }` + - `"completed"` - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `type: "apply_patch_call"` - - `file_id: optional string` + The type of the item. Always `apply_patch_call`. - File ID for the mask image. + - `"apply_patch_call"` - - `image_url: optional string` + - `agent: optional object { agent_name }` - Base64-encoded mask image. + The agent that produced this item. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `agent_name: string` - The image generation model to use. Default: `gpt-image-1`. + The canonical name of the agent that produced this item. - - `string` + - `caller: optional object { type } or object { caller_id, type }` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + The execution context that produced this tool call. - The image generation model to use. Default: `gpt-image-1`. + - `Direct object { type }` - - `"gpt-image-1"` + - `type: "direct"` - - `"gpt-image-1-mini"` + - `"direct"` - - `"gpt-image-1.5"` + - `Program object { caller_id, type }` - - `moderation: optional "auto" or "low"` + - `caller_id: string` - Moderation level for the generated image. Default: `auto`. + The call ID of the program item that produced this tool call. - - `"auto"` + - `type: "program"` - - `"low"` + - `"program"` - - `output_compression: optional number` + - `created_by: optional string` - Compression level for the output image. Default: 100. + The ID of the entity that created this tool call. - - `output_format: optional "png" or "webp" or "jpeg"` + - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + The output emitted by an apply patch tool call. - - `"png"` + - `id: string` - - `"webp"` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - - `"jpeg"` + - `call_id: string` - - `partial_images: optional number` + The unique ID of the apply patch tool call generated by the model. - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + - `status: "completed" or "failed"` - - `quality: optional "low" or "medium" or "high" or "auto"` + The status of the apply patch tool call output. One of `completed` or `failed`. - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + - `"completed"` - - `"low"` + - `"failed"` - - `"medium"` + - `type: "apply_patch_call_output"` - - `"high"` + The type of the item. Always `apply_patch_call_output`. - - `"auto"` + - `"apply_patch_call_output"` - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `agent: optional object { agent_name }` - 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 agent that produced this item. - - `string` + - `agent_name: string` - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + The canonical name of the agent that produced this item. - 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 }` - - `"1024x1024"` + The execution context that produced this tool call. - - `"1024x1536"` + - `Direct object { type }` - - `"1536x1024"` + - `type: "direct"` - - `"auto"` + - `"direct"` - - `LocalShell object { type }` + - `Program object { caller_id, type }` - A tool that allows the model to execute shell commands in a local environment. + - `caller_id: string` - - `type: "local_shell"` + The call ID of the program item that produced this tool call. - The type of the local shell tool. Always `local_shell`. + - `type: "program"` - - `"local_shell"` + - `"program"` - - `Shell object { type, allowed_callers, environment }` + - `created_by: optional string` - A tool that allows the model to execute shell commands. + The ID of the entity that created this tool call output. - - `type: "shell"` + - `output: optional string` - The type of the shell tool. Always `shell`. + Optional textual output returned by the apply patch tool. - - `"shell"` + - `McpListTools object { id, server_label, tools, 3 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + A list of tools available on an MCP server. - The tool invocation context(s). + - `id: string` - - `"direct"` + The unique ID of the list. + + - `server_label: string` + + The label of the MCP server. - - `"programmatic"` + - `tools: array of object { input_schema, name, annotations, description }` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + The tools available on the server. - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + - `input_schema: unknown` - - `type: "container_auto"` + The JSON schema describing the tool's input. - Automatically creates a container for this request + - `name: string` - - `"container_auto"` + The name of the tool. - - `file_ids: optional array of string` + - `annotations: optional unknown` - An optional list of uploaded files to make available to your code. + Additional annotations about the tool. - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + - `description: optional string` - The memory limit for the container. + The description of the tool. - - `"1g"` + - `type: "mcp_list_tools"` - - `"4g"` + The type of the item. Always `mcp_list_tools`. - - `"16g"` + - `"mcp_list_tools"` - - `"64g"` + - `agent: optional object { agent_name }` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + The agent that produced this item. - Network access policy for the container. + - `agent_name: string` - - `BetaContainerNetworkPolicyDisabled object { type }` + The canonical name of the agent that produced this item. - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + - `error: optional string` - - `skills: optional array of BetaSkillReference or BetaInlineSkill` + Error message if the server could not list tools. - An optional list of skills referenced by id or inline data. + - `McpApprovalRequest object { id, arguments, name, 3 more }` - - `BetaSkillReference object { skill_id, type, version }` + A request for human approval of a tool invocation. - - `skill_id: string` + - `id: string` - The ID of the referenced skill. + The unique ID of the approval request. - - `type: "skill_reference"` + - `arguments: string` - References a skill created with the /v1/skills endpoint. + A JSON string of arguments for the tool. - - `"skill_reference"` + - `name: string` - - `version: optional string` + The name of the tool to run. - Optional skill version. Use a positive integer or 'latest'. Omit for default. + - `server_label: string` - - `BetaInlineSkill object { description, name, source, type }` + The label of the MCP server making the request. - - `description: string` + - `type: "mcp_approval_request"` - The description of the skill. + The type of the item. Always `mcp_approval_request`. - - `name: string` + - `"mcp_approval_request"` - The name of the skill. + - `agent: optional object { agent_name }` - - `source: BetaInlineSkillSource` + The agent that produced this item. - Inline skill payload + - `agent_name: string` - - `data: string` + The canonical name of the agent that produced this item. - Base64-encoded skill zip bundle. + - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` - - `media_type: "application/zip"` + A response to an MCP approval request. - The media type of the inline skill payload. Must be `application/zip`. + - `id: string` - - `"application/zip"` + The unique ID of the approval response - - `type: "base64"` + - `approval_request_id: string` - The type of the inline skill source. Must be `base64`. + The ID of the approval request being answered. - - `"base64"` + - `approve: boolean` - - `type: "inline"` + Whether the request was approved. - Defines an inline skill for this request. + - `type: "mcp_approval_response"` - - `"inline"` + The type of the item. Always `mcp_approval_response`. - - `BetaLocalEnvironment object { type, skills }` + - `"mcp_approval_response"` - - `type: "local"` + - `agent: optional object { agent_name }` - Use a local computer environment. + The agent that produced this item. - - `"local"` + - `agent_name: string` - - `skills: optional array of BetaLocalSkill` + The canonical name of the agent that produced this item. - An optional list of skills. + - `reason: optional string` - - `description: string` + Optional reason for the decision. - The description of the skill. + - `McpCall object { id, arguments, name, 7 more }` - - `name: string` + An invocation of a tool on an MCP server. - The name of the skill. + - `id: string` - - `path: string` + The unique ID of the tool call. - The path to the directory containing the skill. + - `arguments: string` - - `BetaContainerReference object { container_id, type }` + A JSON string of the arguments passed to the tool. - - `container_id: string` + - `name: string` - The ID of the referenced container. + The name of the tool that was run. - - `type: "container_reference"` + - `server_label: string` - References a container created with the /v1/containers endpoint + The label of the MCP server running the tool. - - `"container_reference"` + - `type: "mcp_call"` - - `Custom object { name, type, allowed_callers, 3 more }` + The type of the item. Always `mcp_call`. - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + - `"mcp_call"` - - `name: string` + - `agent: optional object { agent_name }` - The name of the custom tool, used to identify it in tool calls. + The agent that produced this item. - - `type: "custom"` + - `agent_name: string` - The type of the custom tool. Always `custom`. + The canonical name of the agent that produced this item. - - `"custom"` + - `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 tool 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`. - Optional description of the custom tool, used to provide more context. + - `"in_progress"` - - `format: optional object { type } or object { definition, syntax, type }` + - `"completed"` - The input format for the custom tool. Default is unconstrained text. + - `"incomplete"` - - `Text object { type }` + - `"calling"` - Unconstrained free-form text. + - `"failed"` - - `type: "text"` + - `CustomToolCall object { id, call_id, input, 7 more }` - Unconstrained text format. Always `text`. + - `id: string` - - `"text"` + The unique ID of the custom tool call item. - - `Grammar object { definition, syntax, type }` + - `call_id: string` - A grammar defined by the user. + An identifier used to map this custom tool call to a tool call output. - - `definition: string` + - `input: string` - The grammar definition. + The input for the custom tool call generated by the model. - - `syntax: "lark" or "regex"` + - `name: string` - The syntax of the grammar definition. One of `lark` or `regex`. + The name of the custom tool being called. - - `"lark"` + - `status: "in_progress" or "completed" or "incomplete"` - - `"regex"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `type: "grammar"` + - `"in_progress"` - Grammar format. Always `grammar`. + - `"completed"` - - `"grammar"` + - `"incomplete"` - - `Namespace object { description, name, tools, type }` + - `type: "custom_tool_call"` - Groups function/custom tools under a shared namespace. + The type of the custom tool call. Always `custom_tool_call`. - - `description: string` + - `"custom_tool_call"` - A description of the namespace shown to the model. + - `agent: optional object { agent_name }` - - `name: string` + The agent that produced this item. - The namespace name used in tool calls (for example, `crm`). + - `agent_name: string` - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + The canonical name of the agent that produced this item. - The function/custom tools available inside this namespace. + - `caller: optional object { type } or object { caller_id, type }` - - `Function object { name, type, allowed_callers, 5 more }` + The execution context that produced this tool call. - - `name: string` + - `Direct object { type }` - - `type: "function"` + - `type: "direct"` - - `"function"` + - `"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"` - - `defer_loading: optional boolean` + - `"program"` - 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]` + - `namespace: optional string` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + The namespace of the custom tool being called. - - `parameters: optional unknown` + - `CustomToolCallOutput object { id, call_id, output, 5 more }` - - `strict: optional boolean` + - `id: string` - 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 unique ID of the custom tool call output item. - - `Custom object { name, type, allowed_callers, 3 more }` + - `call_id: string` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + The call ID, used to map this custom tool call output to a custom tool call. - - `name: string` + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - The name of the custom tool, used to identify it in tool calls. + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `type: "custom"` + - `StringOutput = string` - The type of the custom tool. Always `custom`. + A string of the output of the custom tool call. - - `"custom"` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `allowed_callers: optional array of "direct" or "programmatic"` + Text, image, or file output of the custom tool call. - The tool invocation context(s). + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `"direct"` + A text input to the model. - - `"programmatic"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `defer_loading: optional boolean` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - Whether this tool should be deferred and discovered via tool search. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `description: optional string` + A file input to the model. - Optional description of the custom tool, used to provide more context. + - `status: "in_progress" or "completed" or "incomplete"` - - `format: optional object { type } or object { definition, syntax, type }` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - The input format for the custom tool. Default is unconstrained text. + - `"in_progress"` - - `Text object { type }` + - `"completed"` - Unconstrained free-form text. + - `"incomplete"` - - `type: "text"` + - `type: "custom_tool_call_output"` - Unconstrained text format. Always `text`. + The type of the custom tool call output. Always `custom_tool_call_output`. - - `"text"` + - `"custom_tool_call_output"` - - `Grammar object { definition, syntax, type }` + - `agent: optional object { agent_name }` - A grammar defined by the user. + The agent that produced this item. - - `definition: string` + - `agent_name: string` - The grammar definition. + The canonical name of the agent that produced this item. - - `syntax: "lark" or "regex"` + - `caller: optional object { type } or object { caller_id, type }` - The syntax of the grammar definition. One of `lark` or `regex`. + The execution context that produced this tool call. - - `"lark"` + - `Direct object { type }` - - `"regex"` + - `type: "direct"` - - `type: "grammar"` + The caller type. Always `direct`. - Grammar format. Always `grammar`. + - `"direct"` - - `"grammar"` + - `Program object { caller_id, type }` - - `type: "namespace"` + - `caller_id: string` - The type of the tool. Always `namespace`. + The call ID of the program item that produced this tool call. - - `"namespace"` + - `type: "program"` - - `ToolSearch object { type, description, execution, parameters }` + The caller type. Always `program`. - Hosted or BYOT tool search configuration for deferred tools. + - `"program"` - - `type: "tool_search"` + - `created_by: optional string` - The type of the tool. Always `tool_search`. + The identifier of the actor that created the item. - - `"tool_search"` + - `first_id: string` - - `description: optional string` + The ID of the first item in the list. - Description shown to the model for a client-executed tool search tool. + - `has_more: boolean` - - `execution: optional "server" or "client"` + Whether there are more items available. - Whether tool search is executed by the server or by the client. + - `last_id: string` - - `"server"` + The ID of the last item in the list. - - `"client"` + - `object: "list"` - - `parameters: optional unknown` + The type of object returned, must be `list`. - Parameter schema for a client-executed tool search tool. + - `"list"` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` +### Example - 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). +```http +curl https://api.openai.com/v1/responses/$RESPONSE_ID/input_items \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` +#### Response - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. +```json +{ + "data": [ + { + "id": "id", + "content": [ + { + "text": "text", + "type": "input_text", + "prompt_cache_breakpoint": { + "mode": "explicit" + } + } + ], + "role": "user", + "type": "message", + "agent": { + "agent_name": "agent_name" + }, + "status": "in_progress" + } + ], + "first_id": "first_id", + "has_more": true, + "last_id": "last_id", + "object": "list" +} +``` - - `"web_search_preview"` +### Example - - `"web_search_preview_2025_03_11"` +```http +curl https://api.openai.com/v1/responses/resp_abc123/input_items \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `search_content_types: optional array of "text" or "image"` +#### Response - - `"text"` +```json +{ + "object": "list", + "data": [ + { + "id": "msg_abc123", + "type": "message", + "role": "user", + "content": [ + { + "type": "input_text", + "text": "Tell me a three sentence bedtime story about a unicorn." + } + ] + } + ], + "first_id": "msg_abc123", + "last_id": "msg_abc123", + "has_more": false +} +``` - - `"image"` +## Domain Types - - `search_context_size: optional "low" or "medium" or "high"` +### Beta Response Item List - 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. +- `BetaResponseItemList object { data, first_id, has_more, 2 more }` - - `"low"` + A list of Response items. - - `"medium"` + - `data: array of BetaResponseInputMessageItem or BetaResponseOutputMessage or object { id, queries, status, 3 more } or 29 more` - - `"high"` + A list of items used to generate this response. - - `user_location: optional object { type, city, country, 2 more }` + - `BetaResponseInputMessageItem object { id, content, role, 3 more }` - The user's location. + - `id: string` - - `type: "approximate"` + The unique ID of the message input. - The type of location approximation. Always `approximate`. + - `content: BetaResponseInputMessageContentList` - - `"approximate"` + A list of one or many input items to the model, containing different content + types. - - `city: optional string` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - Free text input for the city of the user, e.g. `San Francisco`. + A text input to the model. - - `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 input to the model. - - `region: optional string` + - `type: "input_text"` - Free text input for the region of the user, e.g. `California`. + The type of the input item. Always `input_text`. - - `timezone: optional string` + - `"input_text"` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + - `prompt_cache_breakpoint: optional object { mode }` - - `ApplyPatch object { type, allowed_callers }` + 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. - Allows the assistant to create, delete, or update files using unified diffs. + - `mode: "explicit"` - - `type: "apply_patch"` + The breakpoint mode. Always `explicit`. - The type of the tool. Always `apply_patch`. + - `"explicit"` - - `"apply_patch"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `allowed_callers: optional array of "direct" or "programmatic"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - The tool invocation context(s). + - `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`. - - `"programmatic"` + - `"low"` - - `type: "tool_search_output"` + - `"high"` - The item type. Always `tool_search_output`. + - `"auto"` - - `"tool_search_output"` + - `"original"` - - `id: optional string` + - `type: "input_image"` - The unique ID of this tool search output. + The type of the input item. Always `input_image`. - - `agent: optional object { agent_name }` + - `"input_image"` - The agent that produced this item. + - `file_id: optional string` - - `agent_name: string` + The ID of the file to be sent to the model. - The canonical name of the agent that produced this item. + - `image_url: optional string` - - `call_id: 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 unique ID of the tool search call generated by the model. + - `prompt_cache_breakpoint: optional object { mode }` - - `execution: optional "server" or "client"` + 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 tool search was executed by the server or by the client. + - `mode: "explicit"` - - `"server"` + The breakpoint mode. Always `explicit`. - - `"client"` + - `"explicit"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - The status of the tool search output. + A file input to the model. - - `"in_progress"` + - `type: "input_file"` - - `"completed"` + The type of the input item. Always `input_file`. - - `"incomplete"` + - `"input_file"` - - `AdditionalTools object { role, tools, type, 2 more }` + - `detail: optional "auto" or "low" or "high"` - - `role: "developer"` + 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 role that provided the additional tools. Only `developer` is supported. + - `"auto"` - - `"developer"` + - `"low"` - - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` + - `"high"` - A list of additional tools made available at this item. + - `file_data: optional string` - - `Function object { name, parameters, strict, 5 more }` + The content of the file to be sent to the model. - Defines a function in your own code the model can choose to call. Learn more about [function calling](https://platform.openai.com/docs/guides/function-calling). + - `file_id: optional string` - - `name: string` + The ID of the file to be sent to the model. - The name of the function to call. + - `file_url: optional string` - - `parameters: map[unknown]` + The URL of the file to be sent to the model. - A JSON schema object describing the parameters of the function. + - `filename: optional string` - - `strict: boolean` + The name of the file to be sent to the model. - Whether strict parameter validation is enforced for this function tool. + - `prompt_cache_breakpoint: optional object { mode }` - - `type: "function"` + 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 type of the function tool. Always `function`. + - `mode: "explicit"` - - `"function"` + The breakpoint mode. Always `explicit`. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"explicit"` - The tool invocation context(s). + - `role: "user" or "system" or "developer"` - - `"direct"` + The role of the message input. One of `user`, `system`, or `developer`. - - `"programmatic"` + - `"user"` - - `defer_loading: optional boolean` + - `"system"` - Whether this function is deferred and loaded via tool search. + - `"developer"` - - `description: optional string` + - `type: "message"` - A description of the function. Used by the model to determine whether or not to call the function. + The type of the message input. Always set to `message`. - - `output_schema: optional map[unknown]` + - `"message"` - A JSON schema object describing the JSON value encoded in string outputs for this function. + - `agent: optional object { agent_name }` - - `FileSearch object { type, vector_store_ids, filters, 2 more }` + The agent that produced this item. - 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). + - `agent_name: string` - - `type: "file_search"` + The canonical name of the agent that produced this item. - The type of the file search tool. Always `file_search`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"file_search"` + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `vector_store_ids: array of string` + - `"in_progress"` - The IDs of the vector stores to search. + - `"completed"` - - `filters: optional object { key, type, value } or object { filters, type }` + - `"incomplete"` - A filter to apply. + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - - `ComparisonFilter object { key, type, value }` + An output message from the model. - A filter used to compare a specified attribute key to a given value using a defined comparison operation. + - `id: string` - - `key: string` + The unique ID of the output message. - The key to compare against the value. + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - - `type: "eq" or "ne" or "gt" or 5 more` + The content of the output message. - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - - `eq`: equals - - `ne`: not equal - - `gt`: greater than - - `gte`: greater than or equal - - `lt`: less than - - `lte`: less than or equal - - `in`: in - - `nin`: not in + A text output from the model. - - `"eq"` + - `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 }` - - `"ne"` + The annotations of the text output. - - `"gt"` + - `FileCitation object { file_id, filename, index, type }` - - `"gte"` + A citation to a file. - - `"lt"` + - `file_id: string` - - `"lte"` + The ID of the file. - - `"in"` + - `filename: string` - - `"nin"` + The filename of the file cited. - - `value: string or number or boolean or array of string or number` + - `index: number` - The value to compare against the attribute key; supports string, number, or boolean types. + The index of the file in the list of files. - - `string` + - `type: "file_citation"` - - `number` + The type of the file citation. Always `file_citation`. - - `boolean` + - `"file_citation"` - - `array of string or number` + - `URLCitation object { end_index, start_index, title, 2 more }` - - `string` + A citation for a web resource used to generate a model response. - - `number` + - `end_index: number` - - `CompoundFilter object { filters, type }` + The index of the last character of the URL citation in the message. - Combine multiple filters using `and` or `or`. + - `start_index: number` - - `filters: array of object { key, type, value } or unknown` + The index of the first character of the URL citation in the message. - Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. + - `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"` - - `key: string` + The type of the URL citation. Always `url_citation`. - The key to compare against the value. + - `"url_citation"` - - `type: "eq" or "ne" or "gt" or 5 more` + - `url: string` - Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. + The URL of the web resource. - - `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 + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - - `"eq"` + A citation for a container file used to generate a model response. - - `"ne"` + - `container_id: string` - - `"gt"` + The ID of the container file. - - `"gte"` + - `end_index: number` - - `"lt"` + The index of the last character of the container file citation in the message. - - `"lte"` + - `file_id: string` - - `"in"` + The ID of the file. - - `"nin"` + - `filename: string` - - `value: string or number or boolean or array of string or number` + The filename of the container file cited. - The value to compare against the attribute key; supports string, number, or boolean types. + - `start_index: number` - - `string` + The index of the first character of the container file citation in the message. - - `number` + - `type: "container_file_citation"` - - `boolean` + The type of the container file citation. Always `container_file_citation`. - - `array of string or number` + - `"container_file_citation"` - - `string` + - `FilePath object { file_id, index, type }` - - `number` + A path to a file. - - `unknown` + - `file_id: string` - - `type: "and" or "or"` + The ID of the file. - Type of operation: `and` or `or`. + - `index: number` - - `"and"` + The index of the file in the list of files. - - `"or"` + - `type: "file_path"` - - `max_num_results: optional number` + The type of the file path. Always `file_path`. - The maximum number of results to return. This number should be between 1 and 50 inclusive. + - `"file_path"` - - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - Ranking options for search. + - `token: string` - - `hybrid_search: optional object { embedding_weight, text_weight }` + - `bytes: array of number` - Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + - `logprob: number` - - `embedding_weight: number` + - `top_logprobs: array of object { token, bytes, logprob }` - The weight of the embedding in the reciprocal ranking fusion. + - `token: string` - - `text_weight: number` + - `bytes: array of number` - The weight of the text in the reciprocal ranking fusion. + - `logprob: number` - - `ranker: optional "auto" or "default-2024-11-15"` + - `text: string` - The ranker to use for the file search. + The text output from the model. - - `"auto"` + - `type: "output_text"` - - `"default-2024-11-15"` + The type of the output text. Always `output_text`. - - `score_threshold: optional number` + - `"output_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. + - `BetaResponseOutputRefusal object { refusal, type }` - - `Computer object { type }` + A refusal from the model. - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `refusal: string` - - `type: "computer"` + The refusal explanation from the model. - The type of the computer tool. Always `computer`. + - `type: "refusal"` - - `"computer"` + The type of the refusal. Always `refusal`. - - `ComputerUsePreview object { display_height, display_width, environment, type }` + - `"refusal"` - A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). + - `role: "assistant"` - - `display_height: number` + The role of the output message. Always `assistant`. - The height of the computer display. + - `"assistant"` - - `display_width: number` + - `status: "in_progress" or "completed" or "incomplete"` - The width of the computer display. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `environment: "windows" or "mac" or "linux" or 2 more` + - `"in_progress"` - The type of computer environment to control. + - `"completed"` - - `"windows"` + - `"incomplete"` - - `"mac"` + - `type: "message"` - - `"linux"` + The type of the output message. Always `message`. - - `"ubuntu"` + - `"message"` - - `"browser"` + - `agent: optional object { agent_name }` - - `type: "computer_use_preview"` + The agent that produced this item. - The type of the computer use tool. Always `computer_use_preview`. + - `agent_name: string` - - `"computer_use_preview"` + The canonical name of the agent that produced this item. - - `WebSearch object { type, filters, search_context_size, user_location }` + - `phase: optional "commentary" or "final_answer"` - Search the Internet for sources related to the prompt. Learn more about the - [web search tool](/docs/guides/tools-web-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. - - `type: "web_search" or "web_search_2025_08_26"` + - `"commentary"` - The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. + - `"final_answer"` - - `"web_search"` + - `FileSearchCall object { id, queries, status, 3 more }` - - `"web_search_2025_08_26"` + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - - `filters: optional object { allowed_domains }` + - `id: string` - Filters for the search. + The unique ID of the file search tool call. - - `allowed_domains: optional array of string` + - `queries: array of string` - Allowed domains for the search. If not provided, all domains are allowed. - Subdomains of the provided domains are allowed as well. + The queries used to search for files. - Example: `["pubmed.ncbi.nlm.nih.gov"]` + - `status: "in_progress" or "searching" or "completed" or 2 more` - - `search_context_size: optional "low" or "medium" or "high"` + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - 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. + - `"in_progress"` - - `"low"` + - `"searching"` - - `"medium"` + - `"completed"` - - `"high"` + - `"incomplete"` - - `user_location: optional object { city, country, region, 2 more }` + - `"failed"` - The approximate location of the user. + - `type: "file_search_call"` - - `city: optional string` + The type of the file search tool call. Always `file_search_call`. - Free text input for the city of the user, e.g. `San Francisco`. + - `"file_search_call"` - - `country: optional string` + - `agent: optional object { agent_name }` - The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. + The agent that produced this item. - - `region: optional string` + - `agent_name: string` - Free text input for the region of the user, e.g. `California`. + The canonical name of the agent that produced this item. - - `timezone: optional string` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. + The results of the file search tool call. - - `type: optional "approximate"` + - `attributes: optional map[string or number or boolean]` - The type of location approximation. Always `approximate`. + 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. - - `"approximate"` + - `string` - - `Mcp object { server_label, type, allowed_callers, 9 more }` + - `number` - Give the model access to additional tools via remote Model Context Protocol - (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). + - `boolean` - - `server_label: string` + - `file_id: optional string` - A label for this MCP server, used to identify it in tool calls. + The unique ID of the file. - - `type: "mcp"` + - `filename: optional string` - The type of the MCP tool. Always `mcp`. + The name of the file. - - `"mcp"` + - `score: optional number` - - `allowed_callers: optional array of "direct" or "programmatic"` + The relevance score of the file - a value between 0 and 1. - The tool invocation context(s). + - `text: optional string` - - `"direct"` + The text that was retrieved from the file. - - `"programmatic"` + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - - `allowed_tools: optional array of string or object { read_only, tool_names }` + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - List of allowed tool names or a filter object. + - `id: string` - - `McpAllowedTools = array of string` + The unique ID of the computer call. - A string array of allowed tool names + - `call_id: string` - - `McpToolFilter object { read_only, tool_names }` + An identifier used when responding to the tool call with output. - A filter object to specify which tools are allowed. + - `pending_safety_checks: array of object { id, code, message }` - - `read_only: optional boolean` + The pending safety checks for the 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. + - `id: string` - - `tool_names: optional array of string` + The ID of the pending safety check. - List of allowed tool names. + - `code: optional string` - - `authorization: optional string` + The type of the pending safety check. - 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. + - `message: optional string` - - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` + Details about the pending safety check. - 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). + - `status: "in_progress" or "completed" or "incomplete"` - Currently supported `connector_id` values are: + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - 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` + - `"in_progress"` - - `"connector_dropbox"` + - `"completed"` - - `"connector_gmail"` + - `"incomplete"` - - `"connector_googlecalendar"` + - `type: "computer_call"` - - `"connector_googledrive"` + The type of the computer call. Always `computer_call`. - - `"connector_microsoftteams"` + - `"computer_call"` - - `"connector_outlookcalendar"` + - `action: optional BetaComputerAction` - - `"connector_outlookemail"` + A click action. - - `"connector_sharepoint"` + - `Click object { button, type, x, 2 more }` - - `defer_loading: optional boolean` + A click action. - Whether this MCP tool is deferred and discovered via tool search. + - `button: "left" or "right" or "wheel" or 2 more` - - `headers: optional map[string]` + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - Optional HTTP headers to send to the MCP server. Use for authentication - or other purposes. + - `"left"` - - `require_approval: optional object { always, never } or "always" or "never"` + - `"right"` - Specify which of the MCP server's tools require approval. + - `"wheel"` - - `McpToolApprovalFilter object { always, never }` + - `"back"` - Specify which of the MCP server's tools require approval. Can be - `always`, `never`, or a filter object associated with tools - that require approval. + - `"forward"` - - `always: optional object { read_only, tool_names }` + - `type: "click"` - A filter object to specify which tools are allowed. + Specifies the event type. For a click action, this property is always `click`. - - `read_only: optional boolean` + - `"click"` - 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. + - `x: number` - - `tool_names: optional array of string` + The x-coordinate where the click occurred. - List of allowed tool names. + - `y: number` - - `never: optional object { read_only, tool_names }` + The y-coordinate where the click occurred. - A filter object to specify which tools are allowed. + - `keys: optional array of string` - - `read_only: optional boolean` + The keys being held while clicking. - 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. + - `DoubleClick object { keys, type, x, y }` - - `tool_names: optional array of string` + A double click action. - List of allowed tool names. + - `keys: array of string` - - `McpToolApprovalSetting = "always" or "never"` + The keys being held while double-clicking. - Specify a single approval policy for all tools. One of `always` or - `never`. When set to `always`, all tools will require approval. When - set to `never`, all tools will not require approval. + - `type: "double_click"` - - `"always"` + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `"never"` + - `"double_click"` - - `server_description: optional string` + - `x: number` - Optional description of the MCP server, used to provide more context. + The x-coordinate where the double click occurred. - - `server_url: optional string` + - `y: number` - The URL for the MCP server. One of `server_url`, `connector_id`, or - `tunnel_id` must be provided. + The y-coordinate where the double click occurred. - - `tunnel_id: optional string` + - `Drag object { path, type, keys }` - 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 drag action. - - `CodeInterpreter object { container, type, allowed_callers }` + - `path: array of object { x, y }` - A tool that runs Python code to help generate a response to a prompt. + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `container: string or object { type, file_ids, memory_limit, network_policy }` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - 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. + - `x: number` - - `string` + The x-coordinate. - The container ID. + - `y: number` - - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` + The y-coordinate. - Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. + - `type: "drag"` - - `type: "auto"` + Specifies the event type. For a drag action, this property is always set to `drag`. - Always `auto`. + - `"drag"` - - `"auto"` + - `keys: optional array of string` - - `file_ids: optional array of string` + The keys being held while dragging the mouse. - An optional list of uploaded files to make available to your code. + - `Keypress object { keys, type }` - - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` + A collection of keypresses the model would like to perform. - The memory limit for the code interpreter container. + - `keys: array of string` - - `"1g"` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - - `"4g"` + - `type: "keypress"` - - `"16g"` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - - `"64g"` + - `"keypress"` - - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` + - `Move object { type, x, y, keys }` - Network access policy for the container. + A mouse move action. - - `BetaContainerNetworkPolicyDisabled object { type }` + - `type: "move"` - - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` + Specifies the event type. For a move action, this property is always set to `move`. - - `type: "code_interpreter"` + - `"move"` - The type of the code interpreter tool. Always `code_interpreter`. + - `x: number` - - `"code_interpreter"` + The x-coordinate to move to. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `y: number` - The tool invocation context(s). + The y-coordinate to move to. - - `"direct"` + - `keys: optional array of string` - - `"programmatic"` + The keys being held while moving the mouse. - - `ProgrammaticToolCalling object { type }` + - `Screenshot object { type }` - - `type: "programmatic_tool_calling"` + A screenshot action. - The type of the tool. Always `programmatic_tool_calling`. + - `type: "screenshot"` - - `"programmatic_tool_calling"` + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `ImageGeneration object { type, action, background, 9 more }` + - `"screenshot"` - A tool that generates images using the GPT image models. + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `type: "image_generation"` + A scroll action. - The type of the image generation tool. Always `image_generation`. + - `scroll_x: number` - - `"image_generation"` + The horizontal scroll distance. - - `action: optional "generate" or "edit" or "auto"` + - `scroll_y: number` - Whether to generate a new image or edit an existing image. Default: `auto`. + The vertical scroll distance. - - `"generate"` + - `type: "scroll"` - - `"edit"` + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `"auto"` + - `"scroll"` - - `background: optional "transparent" or "opaque" or "auto"` + - `x: number` - Background type for the generated image. One of `transparent`, - `opaque`, or `auto`. Default: `auto`. + The x-coordinate where the scroll occurred. - - `"transparent"` + - `y: number` - - `"opaque"` + The y-coordinate where the scroll occurred. - - `"auto"` + - `keys: optional array of string` - - `input_fidelity: optional "high" or "low"` + The keys being held while scrolling. - 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 object { text, type }` - - `"high"` + An action to type in text. - - `"low"` + - `text: string` - - `input_image_mask: optional object { file_id, image_url }` + The text to type. - Optional mask for inpainting. Contains `image_url` - (string, optional) and `file_id` (string, optional). + - `type: "type"` - - `file_id: optional string` + Specifies the event type. For a type action, this property is always set to `type`. - File ID for the mask image. + - `"type"` - - `image_url: optional string` + - `Wait object { type }` - Base64-encoded mask image. + A wait action. - - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `type: "wait"` - The image generation model to use. Default: `gpt-image-1`. + Specifies the event type. For a wait action, this property is always set to `wait`. - - `string` + - `"wait"` - - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` + - `actions: optional BetaComputerActionList` - The image generation model to use. Default: `gpt-image-1`. + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `"gpt-image-1"` + - `Click object { button, type, x, 2 more }` - - `"gpt-image-1-mini"` + A click action. - - `"gpt-image-1.5"` + - `DoubleClick object { keys, type, x, y }` - - `moderation: optional "auto" or "low"` + A double click action. - Moderation level for the generated image. Default: `auto`. + - `Drag object { path, type, keys }` - - `"auto"` + A drag action. - - `"low"` + - `Keypress object { keys, type }` - - `output_compression: optional number` + A collection of keypresses the model would like to perform. - Compression level for the output image. Default: 100. + - `Move object { type, x, y, keys }` - - `output_format: optional "png" or "webp" or "jpeg"` + A mouse move action. - The output format of the generated image. One of `png`, `webp`, or - `jpeg`. Default: `png`. + - `Screenshot object { type }` - - `"png"` + A screenshot action. - - `"webp"` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `"jpeg"` + A scroll action. - - `partial_images: optional number` + - `Type object { text, type }` - Number of partial images to generate in streaming mode, from 0 (default value) to 3. + An action to type in text. - - `quality: optional "low" or "medium" or "high" or "auto"` + - `Wait object { type }` - The quality of the generated image. One of `low`, `medium`, `high`, - or `auto`. Default: `auto`. + A wait action. - - `"low"` + - `agent: optional object { agent_name }` - - `"medium"` + The agent that produced this item. - - `"high"` + - `agent_name: string` - - `"auto"` + The canonical name of the agent that produced this item. - - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `ComputerCallOutput object { id, call_id, output, 5 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`. + - `id: string` - - `string` + The unique ID of the computer call tool output. - - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` + - `call_id: string` - The size of the generated images. For `gpt-image-2` and `gpt-image-2-2026-04-21`, arbitrary resolutions are supported as `WIDTHxHEIGHT` strings, for example `1536x864`. Width and height must both be divisible by 16 and the requested aspect ratio must be between 1:3 and 3:1. Resolutions above `2560x1440` are experimental, and the maximum supported resolution is `3840x2160`. The requested size must also satisfy the model's current pixel and edge limits. The standard sizes `1024x1024`, `1536x1024`, and `1024x1536` are supported by the GPT image models; `auto` is supported for models that allow automatic sizing. For `dall-e-2`, use one of `256x256`, `512x512`, or `1024x1024`. For `dall-e-3`, use one of `1024x1024`, `1792x1024`, or `1024x1792`. + The ID of the computer tool call that produced the output. - - `"1024x1024"` + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `"1024x1536"` + A computer screenshot image used with the computer use tool. - - `"1536x1024"` + - `type: "computer_screenshot"` - - `"auto"` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `LocalShell object { type }` + - `"computer_screenshot"` - A tool that allows the model to execute shell commands in a local environment. + - `file_id: optional string` - - `type: "local_shell"` + The identifier of an uploaded file that contains the screenshot. - The type of the local shell tool. Always `local_shell`. + - `image_url: optional string` - - `"local_shell"` + The URL of the screenshot image. - - `Shell object { type, allowed_callers, environment }` + - `status: "completed" or "incomplete" or "failed" or "in_progress"` - A tool that allows the model to execute shell commands. + The status of the message input. One of `in_progress`, `completed`, or + `incomplete`. Populated when input items are returned via API. - - `type: "shell"` + - `"completed"` - The type of the shell tool. Always `shell`. + - `"incomplete"` - - `"shell"` + - `"failed"` - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"in_progress"` - The tool invocation context(s). + - `type: "computer_call_output"` - - `"direct"` + The type of the computer tool call output. Always `computer_call_output`. - - `"programmatic"` + - `"computer_call_output"` - - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` + The safety checks reported by the API that have been acknowledged by the + developer. - - `BetaLocalEnvironment object { type, skills }` + - `id: string` - - `BetaContainerReference object { container_id, type }` + The ID of the pending safety check. - - `Custom object { name, type, allowed_callers, 3 more }` + - `code: optional string` - 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 pending safety check. - - `name: string` + - `message: optional string` - The name of the custom tool, used to identify it in tool calls. + Details about the pending safety check. - - `type: "custom"` + - `agent: optional object { agent_name }` - The type of the custom tool. Always `custom`. + The agent that produced this item. - - `"custom"` + - `agent_name: string` - - `allowed_callers: optional array of "direct" or "programmatic"` + The canonical name of the agent that produced this item. - The tool invocation context(s). + - `created_by: optional string` - - `"direct"` + The identifier of the actor that created the item. - - `"programmatic"` + - `WebSearchCall object { id, action, status, 2 more }` - - `defer_loading: optional boolean` + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - Whether this tool should be deferred and discovered via tool search. + - `id: string` - - `description: optional string` + The unique ID of the web search tool call. - Optional description of the custom tool, used to provide more context. + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` - - `format: optional object { type } or object { definition, syntax, 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). - The input format for the custom tool. Default is unconstrained text. + - `Search object { type, queries, query, sources }` - - `Text object { type }` + Action type "search" - Performs a web search query. - Unconstrained free-form text. + - `type: "search"` - - `type: "text"` + The action type. - Unconstrained text format. Always `text`. + - `"search"` - - `"text"` + - `queries: optional array of string` - - `Grammar object { definition, syntax, type }` + The search queries. - A grammar defined by the user. + - `query: optional string` - - `definition: string` + The search query. - The grammar definition. + - `sources: optional array of object { type, url }` - - `syntax: "lark" or "regex"` + The sources used in the search. - The syntax of the grammar definition. One of `lark` or `regex`. + - `type: "url"` - - `"lark"` + The type of source. Always `url`. - - `"regex"` + - `"url"` - - `type: "grammar"` + - `url: string` - Grammar format. Always `grammar`. + The URL of the source. - - `"grammar"` + - `OpenPage object { type, url }` - - `Namespace object { description, name, tools, type }` + Action type "open_page" - Opens a specific URL from search results. - Groups function/custom tools under a shared namespace. + - `type: "open_page"` - - `description: string` + The action type. - A description of the namespace shown to the model. + - `"open_page"` - - `name: string` + - `url: optional string` - The namespace name used in tool calls (for example, `crm`). + The URL opened by the model. - - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` + - `FindInPage object { pattern, type, url }` - The function/custom tools available inside this namespace. + Action type "find_in_page": Searches for a pattern within a loaded page. - - `Function object { name, type, allowed_callers, 5 more }` + - `pattern: string` - - `name: string` + The pattern or text to search for within the page. - - `type: "function"` + - `type: "find_in_page"` - - `"function"` + The action type. - - `allowed_callers: optional array of "direct" or "programmatic"` + - `"find_in_page"` - The tool invocation context(s). + - `url: string` - - `"direct"` + The URL of the page searched for the pattern. - - `"programmatic"` + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `defer_loading: optional boolean` + The status of the web search tool call. - Whether this function should be deferred and discovered via tool search. + - `"in_progress"` - - `description: optional string` + - `"searching"` - - `output_schema: optional map[unknown]` + - `"completed"` - A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. + - `"failed"` - - `parameters: optional unknown` + - `type: "web_search_call"` - - `strict: optional boolean` + The type of the web search tool call. Always `web_search_call`. - 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. + - `"web_search_call"` - - `Custom object { name, type, allowed_callers, 3 more }` + - `agent: optional object { agent_name }` - A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) + The agent that produced this item. - - `name: string` + - `agent_name: string` - The name of the custom tool, used to identify it in tool calls. + The canonical name of the agent that produced this item. - - `type: "custom"` + - `FunctionCall object { id, arguments, call_id, 7 more }` - The type of the custom tool. Always `custom`. + - `id: string` - - `"custom"` + The unique ID of the function tool call. - - `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` + - `status: "in_progress" or "completed" or "incomplete"` - Optional description of the custom tool, used to provide more context. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `format: optional object { type } or object { definition, syntax, type }` + - `"in_progress"` - The input format for the custom tool. Default is unconstrained text. + - `"completed"` - - `Text object { type }` + - `"incomplete"` - Unconstrained free-form text. + - `type: "function_call"` - - `type: "text"` + The type of the function tool call. Always `function_call`. - Unconstrained text format. Always `text`. + - `"function_call"` - - `"text"` + - `agent: optional object { agent_name }` - - `Grammar object { definition, syntax, type }` + The agent that produced this item. - A grammar defined by the user. + - `agent_name: string` - - `definition: string` + The canonical name of the agent that produced this item. - The grammar definition. + - `caller: optional object { type } or object { caller_id, type }` - - `syntax: "lark" or "regex"` + The execution context that produced this tool call. - The syntax of the grammar definition. One of `lark` or `regex`. + - `Direct object { type }` - - `"lark"` + - `type: "direct"` - - `"regex"` + - `"direct"` - - `type: "grammar"` + - `Program object { caller_id, type }` - Grammar format. Always `grammar`. + - `caller_id: string` - - `"grammar"` + The call ID of the program item that produced this tool call. - - `type: "namespace"` + - `type: "program"` - The type of the tool. Always `namespace`. + - `"program"` - - `"namespace"` + - `created_by: optional string` - - `ToolSearch object { type, description, execution, parameters }` + The identifier of the actor that created the item. - Hosted or BYOT tool search configuration for deferred tools. + - `namespace: optional string` - - `type: "tool_search"` + The namespace of the function to run. - The type of the tool. Always `tool_search`. + - `FunctionCallOutput object { id, call_id, output, 5 more }` - - `"tool_search"` + - `id: string` - - `description: optional string` + The unique ID of the function call tool output. - 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. + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `"server"` + The output from the function call generated by your code. + Can be a string or an list of output content. - - `"client"` + - `StringOutput = string` - - `parameters: optional unknown` + A string of the output of the function call. - Parameter schema for a client-executed tool search tool. + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` + Text, image, or file output of the function call. - 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). + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `type: "web_search_preview" or "web_search_preview_2025_03_11"` + A text input to the model. - The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `"web_search_preview"` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"web_search_preview_2025_03_11"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `search_content_types: optional array of "text" or "image"` + A file input to the model. - - `"text"` + - `status: "in_progress" or "completed" or "incomplete"` - - `"image"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `search_context_size: optional "low" or "medium" or "high"` + - `"in_progress"` - 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. + - `"completed"` - - `"low"` + - `"incomplete"` - - `"medium"` + - `type: "function_call_output"` - - `"high"` + The type of the function tool call output. Always `function_call_output`. - - `user_location: optional object { type, city, country, 2 more }` + - `"function_call_output"` - The user's location. + - `agent: optional object { agent_name }` - - `type: "approximate"` + The agent that produced this item. - The type of location approximation. Always `approximate`. + - `agent_name: string` - - `"approximate"` + The canonical name of the agent that produced this item. - - `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"` + - `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). + - `AgentMessage object { id, author, content, 3 more }` - - `"direct"` + - `id: string` - - `"programmatic"` + The unique ID of the agent message. - - `type: "additional_tools"` + - `author: string` - The item type. Always `additional_tools`. + The sending agent identity. - - `"additional_tools"` + - `content: array of BetaResponseInputText or BetaResponseOutputText or object { text, type } or 7 more` - - `id: optional string` + Encrypted content sent between agents. - The unique ID of this additional tools item. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `agent: optional object { agent_name }` + A text input to the model. - The agent that produced this item. + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - - `agent_name: string` + A text output from the model. - The canonical name of the agent that produced this item. + - `Text object { text, type }` - - `Reasoning object { id, summary, type, 4 more }` + A text content. - 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). + - `text: string` - - `id: string` + - `type: "text"` - The unique identifier of the reasoning content. + - `"text"` - - `summary: array of object { text, type }` + - `SummaryText object { text, type }` - Reasoning summary content. + A summary text from the model. - `text: string` @@ -212251,23 +213214,9 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok - `"summary_text"` - - `type: "reasoning"` - - The type of the object. Always `reasoning`. - - - `"reasoning"` - - - `agent: optional object { agent_name }` - - The agent that produced this item. - - - `agent_name: string` - - The canonical name of the agent that produced this item. - - - `content: optional array of object { text, type }` + - `ReasoningText object { text, type }` - Reasoning text content. + Reasoning text from the model. - `text: string` @@ -212279,78 +213228,81 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok - `"reasoning_text"` - - `encrypted_content: optional string` + - `BetaResponseOutputRefusal object { refusal, 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. + A refusal from the model. - - `status: optional "in_progress" or "completed" or "incomplete"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - The status of the item. One of `in_progress`, `completed`, or - `incomplete`. Populated when items are returned via API. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `"in_progress"` + - `ComputerScreenshot object { detail, file_id, image_url, 2 more }` - - `"completed"` + A screenshot of a computer. - - `"incomplete"` + - `detail: "low" or "high" or "auto" or "original"` - - `Compaction object { encrypted_content, type, id, agent }` + The detail level of the screenshot image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). + - `"low"` - - `encrypted_content: string` + - `"high"` - The encrypted content of the compaction summary. + - `"auto"` - - `type: "compaction"` + - `"original"` - The type of the item. Always `compaction`. + - `file_id: string` - - `"compaction"` + The identifier of an uploaded file that contains the screenshot. - - `id: optional string` + - `image_url: string` - The ID of the compaction item. + The URL of the screenshot image. - - `agent: optional object { agent_name }` + - `type: "computer_screenshot"` - The agent that produced this item. + Specifies the event type. For a computer screenshot, this property is always set to `computer_screenshot`. - - `agent_name: string` + - `"computer_screenshot"` - The canonical name of the agent that produced this item. + - `prompt_cache_breakpoint: optional object { mode }` - - `ImageGenerationCall object { id, result, status, 2 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. - An image generation request made by the model. + - `mode: "explicit"` - - `id: string` + The breakpoint mode. Always `explicit`. - The unique ID of the image generation call. + - `"explicit"` - - `result: string` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - The generated image encoded in base64. + A file input to the model. - - `status: "in_progress" or "completed" or "generating" or "failed"` + - `EncryptedContent object { encrypted_content, type }` - The status of the image generation call. + Opaque encrypted content that Responses API decrypts inside trusted model execution. - - `"in_progress"` + - `encrypted_content: string` - - `"completed"` + Opaque encrypted content. - - `"generating"` + - `type: "encrypted_content"` - - `"failed"` + The type of the input item. Always `encrypted_content`. - - `type: "image_generation_call"` + - `"encrypted_content"` - The type of the image generation call. Always `image_generation_call`. + - `recipient: string` - - `"image_generation_call"` + The destination agent identity. + + - `type: "agent_message"` + + The type of the item. Always `agent_message`. + + - `"agent_message"` - `agent: optional object { agent_name }` @@ -212360,128 +213312,133 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok The canonical name of the agent that produced this item. - - `CodeInterpreterCall object { id, code, container_id, 4 more }` - - A tool call to run code. + - `MultiAgentCall object { id, action, arguments, 3 more }` - `id: string` - The unique ID of the code interpreter tool call. + The unique ID of the multi-agent call item. - - `code: string` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - The code to run, or null if not available. + The multi-agent action to execute. - - `container_id: string` + - `"spawn_agent"` - The ID of the container used to run the code. + - `"interrupt_agent"` - - `outputs: array of object { logs, type } or object { type, url }` + - `"list_agents"` - The outputs generated by the code interpreter, such as logs or images. - Can be null if no outputs are available. + - `"send_message"` - - `Logs object { logs, type }` + - `"followup_task"` - The logs output from the code interpreter. + - `"wait_agent"` - - `logs: string` + - `arguments: string` - The logs output from the code interpreter. + The JSON string of arguments generated for the action. - - `type: "logs"` + - `call_id: string` - The type of the output. Always `logs`. + The unique ID linking this call to its output. - - `"logs"` + - `type: "multi_agent_call"` - - `Image object { type, url }` + The type of the multi-agent call. Always `multi_agent_call`. - The image output from the code interpreter. + - `"multi_agent_call"` - - `type: "image"` + - `agent: optional object { agent_name }` - The type of the output. Always `image`. + The agent that produced this item. - - `"image"` + - `agent_name: string` - - `url: string` + The canonical name of the agent that produced this item. - The URL of the image output from the code interpreter. + - `MultiAgentCallOutput object { id, action, call_id, 3 more }` - - `status: "in_progress" or "completed" or "incomplete" or 2 more` + - `id: string` - The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. + The unique ID of the multi-agent call output item. - - `"in_progress"` + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `"completed"` + The multi-agent action that produced this result. - - `"incomplete"` + - `"spawn_agent"` - - `"interpreting"` + - `"interrupt_agent"` - - `"failed"` + - `"list_agents"` - - `type: "code_interpreter_call"` + - `"send_message"` - The type of the code interpreter tool call. Always `code_interpreter_call`. + - `"followup_task"` - - `"code_interpreter_call"` + - `"wait_agent"` - - `agent: optional object { agent_name }` + - `call_id: string` - The agent that produced this item. + The unique ID of the multi-agent call. - - `agent_name: string` + - `output: array of BetaResponseOutputText` - The canonical name of the agent that produced this item. + Text output returned by the multi-agent action. - - `LocalShellCall object { id, action, call_id, 3 more }` + - `annotations: array of object { file_id, filename, index, type } or object { end_index, start_index, title, 2 more } or object { container_id, end_index, file_id, 3 more } or object { file_id, index, type }` - A tool call to run a command on the local shell. + The annotations of the text output. - - `id: string` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - The unique ID of the local shell call. + - `text: string` - - `action: object { command, env, type, 3 more }` + The text output from the model. - Execute a shell command on the server. + - `type: "output_text"` - - `command: array of string` + The type of the output text. Always `output_text`. - The command to run. + - `type: "multi_agent_call_output"` - - `env: map[string]` + The type of the multi-agent result. Always `multi_agent_call_output`. - Environment variables to set for the command. + - `"multi_agent_call_output"` - - `type: "exec"` + - `agent: optional object { agent_name }` - The type of the local shell action. Always `exec`. + The agent that produced this item. - - `"exec"` + - `agent_name: string` - - `timeout_ms: optional number` + The canonical name of the agent that produced this item. - Optional timeout in milliseconds for the command. + - `ToolSearchCall object { id, arguments, call_id, 5 more }` - - `user: optional string` + - `id: string` - Optional user to run the command as. + The unique ID of the tool search call item. - - `working_directory: optional string` + - `arguments: unknown` - Optional working directory to run the command in. + Arguments used for the tool search call. - `call_id: string` - The unique ID of the local shell tool call generated by the model. + 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 local shell call. + The status of the tool search call item that was recorded. - `"in_progress"` @@ -212489,11 +213446,11 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok - `"incomplete"` - - `type: "local_shell_call"` + - `type: "tool_search_call"` - The type of the local shell call. Always `local_shell_call`. + The type of the item. Always `tool_search_call`. - - `"local_shell_call"` + - `"tool_search_call"` - `agent: optional object { agent_name }` @@ -212503,35 +213460,31 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok The canonical name of the agent that produced this item. - - `LocalShellCallOutput object { id, output, type, 2 more }` - - The output of a local shell tool call. - - - `id: string` + - `created_by: optional string` - The unique ID of the local shell tool call generated by the model. + The identifier of the actor that created the item. - - `output: string` + - `ToolSearchOutput object { id, call_id, execution, 5 more }` - A JSON string of the output of the local shell tool call. + - `id: string` - - `type: "local_shell_call_output"` + The unique ID of the tool search output item. - The type of the local shell tool call output. Always `local_shell_call_output`. + - `call_id: string` - - `"local_shell_call_output"` + The unique ID of the tool search call generated by the model. - - `agent: optional object { agent_name }` + - `execution: "server" or "client"` - The agent that produced this item. + Whether tool search was executed by the server or by the client. - - `agent_name: string` + - `"server"` - The canonical name of the agent that produced this item. + - `"client"` - - `status: optional "in_progress" or "completed" or "incomplete"` + - `status: "in_progress" or "completed" or "incomplete"` - The status of the item. One of `in_progress`, `completed`, or `incomplete`. + The status of the tool search output item that was recorded. - `"in_progress"` @@ -212539,1174 +213492,1196 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok - `"incomplete"` - - `ShellCall object { action, call_id, type, 5 more }` + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - A tool representing a request to execute one or more shell commands. + The loaded tool definitions returned by tool search. - - `action: object { commands, max_output_length, timeout_ms }` + - `Function object { name, parameters, strict, 5 more }` - The shell commands and limits that describe how to run the tool call. + 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). - - `commands: array of string` + - `name: string` - Ordered shell commands for the execution environment to run. + The name of the function to call. - - `max_output_length: optional number` + - `parameters: map[unknown]` - Maximum number of UTF-8 characters to capture from combined stdout and stderr output. + A JSON schema object describing the parameters of the function. - - `timeout_ms: optional number` + - `strict: boolean` - Maximum wall-clock time in milliseconds to allow the shell commands to run. + Whether strict parameter validation is enforced for this function tool. - - `call_id: string` + - `type: "function"` - The unique ID of the shell tool call generated by the model. + The type of the function tool. Always `function`. - - `type: "shell_call"` + - `"function"` - The type of the item. Always `shell_call`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"shell_call"` + The tool invocation context(s). - - `id: optional string` + - `"direct"` - The unique ID of the shell tool call. Populated when this item is returned via API. + - `"programmatic"` - - `agent: optional object { agent_name }` + - `defer_loading: optional boolean` - The agent that produced this item. + Whether this function is deferred and loaded via tool search. - - `agent_name: string` + - `description: optional string` - The canonical name of the agent that produced this item. + A description of the function. Used by the model to determine whether or not to call the function. - - `caller: optional object { type } or object { caller_id, type }` + - `output_schema: optional map[unknown]` - The execution context that produced this tool call. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `Direct object { type }` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `type: "direct"` + 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 caller type. Always `direct`. + - `type: "file_search"` - - `"direct"` + The type of the file search tool. Always `file_search`. - - `Program object { caller_id, type }` + - `"file_search"` - - `caller_id: string` + - `vector_store_ids: array of string` - The call ID of the program item that produced this tool call. + The IDs of the vector stores to search. - - `type: "program"` + - `filters: optional object { key, type, value } or object { filters, type }` - The caller type. Always `program`. + A filter to apply. - - `"program"` + - `ComparisonFilter object { key, type, value }` - - `environment: optional BetaLocalEnvironment or BetaContainerReference` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The environment to execute the shell commands in. + - `key: string` - - `BetaLocalEnvironment object { type, skills }` + The key to compare against the value. - - `BetaContainerReference object { container_id, type }` + - `type: "eq" or "ne" or "gt" or 5 more` - - `status: optional "in_progress" or "completed" or "incomplete"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. + - `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 - - `"in_progress"` + - `"eq"` - - `"completed"` + - `"ne"` - - `"incomplete"` + - `"gt"` - - `ShellCallOutput object { call_id, output, type, 5 more }` + - `"gte"` - The streamed output items emitted by a shell tool call. + - `"lt"` - - `call_id: string` + - `"lte"` - The unique ID of the shell tool call generated by the model. + - `"in"` - - `output: array of BetaResponseFunctionShellCallOutputContent` + - `"nin"` - Captured chunks of stdout and stderr output, along with their associated outcomes. + - `value: string or number or boolean or array of string or number` - - `outcome: object { type } or object { exit_code, type }` + The value to compare against the attribute key; supports string, number, or boolean types. - The exit or timeout outcome associated with this shell call. + - `string` - - `Timeout object { type }` + - `number` - Indicates that the shell call exceeded its configured time limit. + - `boolean` - - `type: "timeout"` + - `array of string or number` - The outcome type. Always `timeout`. + - `string` - - `"timeout"` + - `number` - - `Exit object { exit_code, type }` + - `CompoundFilter object { filters, type }` - Indicates that the shell commands finished and returned an exit code. + Combine multiple filters using `and` or `or`. - - `exit_code: number` + - `filters: array of object { key, type, value } or unknown` - The exit code returned by the shell process. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `type: "exit"` + - `ComparisonFilter object { key, type, value }` - The outcome type. Always `exit`. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"exit"` + - `key: string` - - `stderr: string` + The key to compare against the value. - Captured stderr output for the shell call. + - `type: "eq" or "ne" or "gt" or 5 more` - - `stdout: string` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - Captured stdout output for the shell 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 - - `type: "shell_call_output"` + - `"eq"` - The type of the item. Always `shell_call_output`. + - `"ne"` - - `"shell_call_output"` + - `"gt"` - - `id: optional string` + - `"gte"` - The unique ID of the shell tool call output. Populated when this item is returned via API. + - `"lt"` - - `agent: optional object { agent_name }` + - `"lte"` - The agent that produced this item. + - `"in"` - - `agent_name: string` + - `"nin"` - The canonical name of the agent that produced this item. + - `value: string or number or boolean or array of string or number` - - `caller: optional object { type } or object { caller_id, type }` + The value to compare against the attribute key; supports string, number, or boolean types. - The execution context that produced this tool call. + - `string` - - `Direct object { type }` + - `number` - - `type: "direct"` + - `boolean` - The caller type. Always `direct`. + - `array of string or number` - - `"direct"` + - `string` - - `Program object { caller_id, type }` + - `number` - - `caller_id: string` + - `unknown` - The call ID of the program item that produced this tool call. + - `type: "and" or "or"` - - `type: "program"` + Type of operation: `and` or `or`. - The caller type. Always `program`. + - `"and"` - - `"program"` + - `"or"` - - `max_output_length: optional number` + - `max_num_results: optional number` - The maximum number of UTF-8 characters captured for this shell call's combined output. + The maximum number of results to return. This number should be between 1 and 50 inclusive. + + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` + + Ranking options for search. + + - `hybrid_search: optional object { embedding_weight, text_weight }` + + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. + + - `embedding_weight: number` + + The weight of the embedding in the reciprocal ranking fusion. + + - `text_weight: number` + + The weight of the text in the reciprocal ranking fusion. + + - `ranker: optional "auto" or "default-2024-11-15"` + + The ranker to use for the file search. + + - `"auto"` + + - `"default-2024-11-15"` + + - `score_threshold: optional number` - - `status: optional "in_progress" or "completed" or "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. - The status of the shell call output. + - `Computer object { type }` - - `"in_progress"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `"completed"` + - `type: "computer"` - - `"incomplete"` + The type of the computer tool. Always `computer`. - - `ApplyPatchCall object { call_id, operation, status, 4 more }` + - `"computer"` - A tool call representing a request to create, delete, or update files using diff patches. + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `call_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 unique ID of the apply patch tool call generated by the model. + - `display_height: number` - - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` + The height of the computer display. - The specific create, delete, or update instruction for the apply_patch tool call. + - `display_width: number` - - `CreateFile object { diff, path, type }` + The width of the computer display. - Instruction for creating a new file via the apply_patch tool. + - `environment: "windows" or "mac" or "linux" or 2 more` - - `diff: string` + The type of computer environment to control. - Unified diff content to apply when creating the file. + - `"windows"` - - `path: string` + - `"mac"` - Path of the file to create relative to the workspace root. + - `"linux"` - - `type: "create_file"` + - `"ubuntu"` - The operation type. Always `create_file`. + - `"browser"` - - `"create_file"` + - `type: "computer_use_preview"` - - `DeleteFile object { path, type }` + The type of the computer use tool. Always `computer_use_preview`. - Instruction for deleting an existing file via the apply_patch tool. + - `"computer_use_preview"` - - `path: string` + - `WebSearch object { type, filters, search_context_size, user_location }` - Path of the file to delete relative to the workspace root. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `type: "delete_file"` + - `type: "web_search" or "web_search_2025_08_26"` - The operation type. Always `delete_file`. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `"delete_file"` + - `"web_search"` - - `UpdateFile object { diff, path, type }` + - `"web_search_2025_08_26"` - Instruction for updating an existing file via the apply_patch tool. + - `filters: optional object { allowed_domains }` - - `diff: string` + Filters for the search. - Unified diff content to apply to the existing file. + - `allowed_domains: optional array of string` - - `path: string` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - Path of the file to update relative to the workspace root. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `type: "update_file"` + - `search_context_size: optional "low" or "medium" or "high"` - The operation type. Always `update_file`. + 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. - - `"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"` + - `user_location: optional object { city, country, region, 2 more }` - - `"completed"` + The approximate location of the user. - - `type: "apply_patch_call"` + - `city: optional string` - The type of the item. Always `apply_patch_call`. + Free text input for the city of the user, e.g. `San Francisco`. - - `"apply_patch_call"` + - `country: optional string` - - `id: optional string` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The unique ID of the apply patch tool call. Populated when this item is returned via API. + - `region: optional string` - - `agent: optional object { agent_name }` + Free text input for the region of the user, e.g. `California`. - The agent that produced this item. + - `timezone: optional string` - - `agent_name: string` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The canonical name of the agent that produced this item. + - `type: optional "approximate"` - - `caller: optional object { type } or object { caller_id, type }` + The type of location approximation. Always `approximate`. - The execution context that produced this tool call. + - `"approximate"` - - `Direct object { type }` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `type: "direct"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - The caller type. Always `direct`. + - `server_label: string` - - `"direct"` + A label for this MCP server, used to identify it in tool calls. - - `Program object { caller_id, type }` + - `type: "mcp"` - - `caller_id: string` + The type of the MCP tool. Always `mcp`. - The call ID of the program item that produced this tool call. + - `"mcp"` - - `type: "program"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The caller type. Always `program`. + The tool invocation context(s). - - `"program"` + - `"direct"` - - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` + - `"programmatic"` - The streamed output emitted by an apply patch tool call. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `call_id: string` + List of allowed tool names or a filter object. - The unique ID of the apply patch tool call generated by the model. + - `McpAllowedTools = array of string` - - `status: "completed" or "failed"` + A string array of allowed tool names - The status of the apply patch tool call output. One of `completed` or `failed`. + - `McpToolFilter object { read_only, tool_names }` - - `"completed"` + A filter object to specify which tools are allowed. - - `"failed"` + - `read_only: optional boolean` - - `type: "apply_patch_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 item. Always `apply_patch_call_output`. + - `tool_names: optional array of string` - - `"apply_patch_call_output"` + List of allowed tool names. - - `id: optional string` + - `authorization: optional string` - The unique ID of the apply patch tool call output. Populated when this item is returned via API. + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - - `agent: optional object { agent_name }` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - The agent that produced this item. + 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). - - `agent_name: string` + Currently supported `connector_id` values are: - The canonical name of the agent that produced this item. + - 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` - - `caller: optional object { type } or object { caller_id, type }` + - `"connector_dropbox"` - The execution context that produced this tool call. + - `"connector_gmail"` - - `Direct object { type }` + - `"connector_googlecalendar"` - - `type: "direct"` + - `"connector_googledrive"` - The caller type. Always `direct`. + - `"connector_microsoftteams"` - - `"direct"` + - `"connector_outlookcalendar"` - - `Program object { caller_id, type }` + - `"connector_outlookemail"` - - `caller_id: string` + - `"connector_sharepoint"` - The call ID of the program item that produced this tool call. + - `defer_loading: optional boolean` - - `type: "program"` + Whether this MCP tool is deferred and discovered via tool search. - The caller type. Always `program`. + - `headers: optional map[string]` - - `"program"` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `output: optional string` + - `require_approval: optional object { always, never } or "always" or "never"` - Optional human-readable log text from the apply patch tool (e.g., patch results or errors). + Specify which of the MCP server's tools require approval. - - `McpListTools object { id, server_label, tools, 3 more }` + - `McpToolApprovalFilter object { always, never }` - A list of tools available on an MCP server. + 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 list. + A filter object to specify which tools are allowed. - - `server_label: string` + - `read_only: optional boolean` - The label of the MCP server. + 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. - - `tools: array of object { input_schema, name, annotations, description }` + - `tool_names: optional array of string` - The tools available on the server. + List of allowed tool names. - - `input_schema: unknown` + - `never: optional object { read_only, tool_names }` - The JSON schema describing the tool's input. + A filter object to specify which tools are allowed. - - `name: string` + - `read_only: optional boolean` - The name of the 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. - - `annotations: optional unknown` + - `tool_names: optional array of string` - Additional annotations about the tool. + List of allowed tool names. - - `description: optional string` + - `McpToolApprovalSetting = "always" or "never"` - The description of the tool. + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - - `type: "mcp_list_tools"` + - `"always"` - The type of the item. Always `mcp_list_tools`. + - `"never"` - - `"mcp_list_tools"` + - `server_description: optional string` - - `agent: optional object { agent_name }` + Optional description of the MCP server, used to provide more context. - The agent that produced this item. + - `server_url: optional string` - - `agent_name: string` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - The canonical name of the agent that produced this item. + - `tunnel_id: optional string` - - `error: optional string` + The Secure MCP Tunnel ID to use instead of a direct server URL. One of + `server_url`, `connector_id`, or `tunnel_id` must be provided. - Error message if the server could not list tools. + - `CodeInterpreter object { container, type, allowed_callers }` - - `McpApprovalRequest object { id, arguments, name, 3 more }` + A tool that runs Python code to help generate a response to a prompt. - A request for human approval of a tool invocation. + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `id: string` + The code interpreter container. Can be a container ID or an object that + specifies uploaded file IDs to make available to your code, along with an + optional `memory_limit` setting. - The unique ID of the approval request. + - `string` - - `arguments: string` + The container ID. - A JSON string of arguments for the tool. + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - - `name: string` + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - The name of the tool to run. + - `type: "auto"` - - `server_label: string` + Always `auto`. - The label of the MCP server making the request. + - `"auto"` - - `type: "mcp_approval_request"` + - `file_ids: optional array of string` - The type of the item. Always `mcp_approval_request`. + An optional list of uploaded files to make available to your code. - - `"mcp_approval_request"` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `agent: optional object { agent_name }` + The memory limit for the code interpreter container. - The agent that produced this item. + - `"1g"` - - `agent_name: string` + - `"4g"` - The canonical name of the agent that produced this item. + - `"16g"` - - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` + - `"64g"` - A response to an MCP approval request. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `approval_request_id: string` + Network access policy for the container. - The ID of the approval request being answered. + - `BetaContainerNetworkPolicyDisabled object { type }` - - `approve: boolean` + - `type: "disabled"` - Whether the request was approved. + Disable outbound network access. Always `disabled`. - - `type: "mcp_approval_response"` + - `"disabled"` - The type of the item. Always `mcp_approval_response`. + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `"mcp_approval_response"` + - `allowed_domains: array of string` - - `id: optional string` + A list of allowed domains when type is `allowlist`. - The unique ID of the approval response + - `type: "allowlist"` - - `agent: optional object { agent_name }` + Allow outbound network access only to specified domains. Always `allowlist`. - The agent that produced this item. + - `"allowlist"` - - `agent_name: string` + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - The canonical name of the agent that produced this item. + Optional domain-scoped secrets for allowlisted domains. - - `reason: optional string` + - `domain: string` - Optional reason for the decision. + The domain associated with the secret. - - `McpCall object { id, arguments, name, 7 more }` + - `name: string` - An invocation of a tool on an MCP server. + The name of the secret to inject for the domain. - - `id: string` + - `value: string` - The unique ID of the tool call. + The secret value to inject for the domain. - - `arguments: string` + - `type: "code_interpreter"` - A JSON string of the arguments passed to the tool. + The type of the code interpreter tool. Always `code_interpreter`. - - `name: string` + - `"code_interpreter"` - The name of the tool that was run. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `server_label: string` + The tool invocation context(s). - The label of the MCP server running the tool. + - `"direct"` - - `type: "mcp_call"` + - `"programmatic"` - The type of the item. Always `mcp_call`. + - `ProgrammaticToolCalling object { type }` - - `"mcp_call"` + - `type: "programmatic_tool_calling"` - - `agent: optional object { agent_name }` + The type of the tool. Always `programmatic_tool_calling`. - The agent that produced this item. + - `"programmatic_tool_calling"` - - `agent_name: string` + - `ImageGeneration object { type, action, background, 9 more }` - The canonical name of the agent that produced this item. + A tool that generates images using the GPT image models. - - `approval_request_id: optional string` + - `type: "image_generation"` - 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 type of the image generation tool. Always `image_generation`. - - `error: optional string` + - `"image_generation"` - The error from the tool call, if any. + - `action: optional "generate" or "edit" or "auto"` - - `output: optional string` + Whether to generate a new image or edit an existing image. Default: `auto`. - The output from the tool call. + - `"generate"` - - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` + - `"edit"` - The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. + - `"auto"` - - `"in_progress"` + - `background: optional "transparent" or "opaque" or "auto"` - - `"completed"` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `"incomplete"` + - `"transparent"` - - `"calling"` + - `"opaque"` - - `"failed"` + - `"auto"` - - `CustomToolCallOutput object { call_id, output, type, 3 more }` + - `input_fidelity: optional "high" or "low"` - The output of a custom tool call from your code, being sent back to the model. + Control how much effort the model will exert to match the style and features, especially facial features, of input images. This parameter is only supported for `gpt-image-1` and `gpt-image-1.5` and later models, unsupported for `gpt-image-1-mini`. Supports `high` and `low`. Defaults to `low`. - - `call_id: string` + - `"high"` - The call ID, used to map this custom tool call output to a custom tool call. + - `"low"` - - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `input_image_mask: optional object { file_id, image_url }` - The output from the custom tool call generated by your code. - Can be a string or an list of output content. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `StringOutput = string` + - `file_id: optional string` - A string of the output of the custom tool call. + File ID for the mask image. - - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` + - `image_url: optional string` - Text, image, or file output of the custom tool call. + Base64-encoded mask image. - - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - A text input to the model. + The image generation model to use. Default: `gpt-image-1`. - - `BetaResponseInputImage object { detail, type, file_id, 2 more }` + - `string` - An image input to the model. Learn about [image inputs](/docs/guides/vision). + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `BetaResponseInputFile object { type, detail, file_data, 4 more }` + The image generation model to use. Default: `gpt-image-1`. - A file input to the model. + - `"gpt-image-1"` - - `type: "custom_tool_call_output"` + - `"gpt-image-1-mini"` - The type of the custom tool call output. Always `custom_tool_call_output`. + - `"gpt-image-1.5"` - - `"custom_tool_call_output"` + - `moderation: optional "auto" or "low"` - - `id: optional string` + Moderation level for the generated image. Default: `auto`. - The unique ID of the custom tool call output in the OpenAI platform. + - `"auto"` - - `agent: optional object { agent_name }` + - `"low"` - The agent that produced this item. + - `output_compression: optional number` - - `agent_name: string` + Compression level for the output image. Default: 100. - The canonical name of the agent that produced this item. + - `output_format: optional "png" or "webp" or "jpeg"` - - `caller: optional object { type } or object { caller_id, type }` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - The execution context that produced this tool call. + - `"png"` - - `Direct object { type }` + - `"webp"` - - `type: "direct"` + - `"jpeg"` - The caller type. Always `direct`. + - `partial_images: optional number` - - `"direct"` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - - `Program object { caller_id, type }` + - `quality: optional "low" or "medium" or "high" or "auto"` - - `caller_id: string` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - The call ID of the program item that produced this tool call. + - `"low"` - - `type: "program"` + - `"medium"` - The caller type. Always `program`. + - `"high"` - - `"program"` + - `"auto"` - - `CustomToolCall object { call_id, input, name, 5 more }` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - A call to a custom tool created 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`. - - `call_id: string` + - `string` - An identifier used to map this custom tool call to a tool call output. + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `input: 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 input for the custom tool call generated by the model. + - `"1024x1024"` - - `name: string` + - `"1024x1536"` - The name of the custom tool being called. + - `"1536x1024"` - - `type: "custom_tool_call"` + - `"auto"` - The type of the custom tool call. Always `custom_tool_call`. + - `LocalShell object { type }` - - `"custom_tool_call"` + A tool that allows the model to execute shell commands in a local environment. - - `id: optional string` + - `type: "local_shell"` - The unique ID of the custom tool call in the OpenAI platform. + The type of the local shell tool. Always `local_shell`. - - `agent: optional object { agent_name }` + - `"local_shell"` - The agent that produced this item. + - `Shell object { type, allowed_callers, environment }` - - `agent_name: string` + A tool that allows the model to execute shell commands. - The canonical name of the agent that produced this item. + - `type: "shell"` - - `caller: optional object { type } or object { caller_id, type }` + The type of the shell tool. Always `shell`. - The execution context that produced this tool call. + - `"shell"` - - `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` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - The call ID of the program item that produced this tool call. + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `type: "program"` + - `type: "container_auto"` - - `"program"` + Automatically creates a container for this request - - `namespace: optional string` + - `"container_auto"` - The namespace of the custom tool being called. + - `file_ids: optional array of string` - - `CompactionTrigger object { type, agent }` + An optional list of uploaded files to make available to your code. - Compacts the current context. Must be the final input item. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `type: "compaction_trigger"` + The memory limit for the container. - The type of the item. Always `compaction_trigger`. + - `"1g"` - - `"compaction_trigger"` + - `"4g"` - - `agent: optional object { agent_name }` + - `"16g"` - The agent that produced this item. + - `"64g"` - - `agent_name: string` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - The canonical name of the agent that produced this item. + Network access policy for the container. - - `ItemReference object { id, agent, type }` + - `BetaContainerNetworkPolicyDisabled object { type }` - An internal identifier for an item to reference. + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `id: string` + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - The ID of the item to reference. + An optional list of skills referenced by id or inline data. - - `agent: optional object { agent_name }` + - `BetaSkillReference object { skill_id, type, version }` - The agent that produced this item. + - `skill_id: string` - - `agent_name: string` + The ID of the referenced skill. - The canonical name of the agent that produced this item. + - `type: "skill_reference"` - - `type: optional "item_reference"` + References a skill created with the /v1/skills endpoint. - The type of item to reference. Always `item_reference`. + - `"skill_reference"` - - `"item_reference"` + - `version: optional string` - - `Program object { id, call_id, code, 3 more }` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - - `id: string` + - `BetaInlineSkill object { description, name, source, type }` - The unique ID of this program item. + - `description: string` - - `call_id: string` + The description of the skill. - The stable call ID of the program item. + - `name: string` - - `code: string` + The name of the skill. - The JavaScript source executed by programmatic tool calling. + - `source: BetaInlineSkillSource` - - `fingerprint: string` + Inline skill payload - Opaque program replay fingerprint that must be round-tripped. + - `data: string` - - `type: "program"` + Base64-encoded skill zip bundle. - The item type. Always `program`. + - `media_type: "application/zip"` - - `"program"` + The media type of the inline skill payload. Must be `application/zip`. - - `agent: optional object { agent_name }` + - `"application/zip"` - The agent that produced this item. + - `type: "base64"` - - `agent_name: string` + The type of the inline skill source. Must be `base64`. - The canonical name of the agent that produced this item. + - `"base64"` - - `ProgramOutput object { id, call_id, result, 3 more }` + - `type: "inline"` - - `id: string` + Defines an inline skill for this request. - The unique ID of this program output item. + - `"inline"` - - `call_id: string` + - `BetaLocalEnvironment object { type, skills }` - The call ID of the program item. + - `type: "local"` - - `result: string` + Use a local computer environment. - The result produced by the program item. + - `"local"` - - `status: "completed" or "incomplete"` + - `skills: optional array of BetaLocalSkill` - The terminal status of the program output. + An optional list of skills. - - `"completed"` + - `description: string` - - `"incomplete"` + The description of the skill. - - `type: "program_output"` + - `name: string` - The item type. Always `program_output`. + The name of the skill. - - `"program_output"` + - `path: string` - - `agent: optional object { agent_name }` + The path to the directory containing the skill. - The agent that produced this item. + - `BetaContainerReference object { container_id, type }` - - `agent_name: string` + - `container_id: string` - The canonical name of the agent that produced this item. + The ID of the referenced container. -- `instructions: optional string` + - `type: "container_reference"` - 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. + References a container created with the /v1/containers endpoint -- `model: optional string` + - `"container_reference"` - 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. + - `Custom object { name, type, allowed_callers, 3 more }` -- `parallel_tool_calls: optional boolean` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - Whether to allow the model to run tool calls in parallel. + - `name: string` -- `personality: optional string or "friendly" or "pragmatic"` + The name of the custom tool, used to identify it in tool calls. - A model-owned style preset to apply to this request. Omit this parameter to use the model's default style. Supported values may expand over time. Values must be at most 64 characters. + - `type: "custom"` - - `string` + The type of the custom tool. Always `custom`. - - `"friendly" or "pragmatic"` + - `"custom"` - A model-owned style preset to apply to this request. Omit this parameter to use the model's default style. Supported values may expand over time. Values must be at most 64 characters. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"friendly"` + The tool invocation context(s). - - `"pragmatic"` + - `"direct"` -- `previous_response_id: optional string` + - `"programmatic"` - 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`. + - `defer_loading: optional boolean` -- `reasoning: optional object { context, effort, generate_summary, 2 more }` + Whether this tool should be deferred and discovered via tool search. - **gpt-5 and o-series models only** Configuration options for [reasoning models](https://platform.openai.com/docs/guides/reasoning). + - `description: optional string` - - `context: optional "auto" or "current_turn" or "all_turns"` + Optional description of the custom tool, used to provide more context. - 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`. + - `format: optional object { type } or object { definition, syntax, type }` - When returned on a response, this is the effective reasoning context mode - used for the response. + The input format for the custom tool. Default is unconstrained text. - - `"auto"` + - `Text object { type }` - - `"current_turn"` + Unconstrained free-form text. - - `"all_turns"` + - `type: "text"` - - `effort: optional "none" or "minimal" or "low" or 4 more` + Unconstrained text format. Always `text`. - 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. + - `"text"` - - `"none"` + - `Grammar object { definition, syntax, type }` - - `"minimal"` + A grammar defined by the user. - - `"low"` + - `definition: string` - - `"medium"` + The grammar definition. - - `"high"` + - `syntax: "lark" or "regex"` - - `"xhigh"` + The syntax of the grammar definition. One of `lark` or `regex`. - - `"max"` + - `"lark"` - - `generate_summary: optional "auto" or "concise" or "detailed"` + - `"regex"` - **Deprecated:** use `summary` instead. + - `type: "grammar"` - 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`. + Grammar format. Always `grammar`. - - `"auto"` + - `"grammar"` - - `"concise"` + - `Namespace object { description, name, tools, type }` - - `"detailed"` + Groups function/custom tools under a shared namespace. - - `mode: optional string or "standard" or "pro"` + - `description: string` - Controls the reasoning execution mode for the request. + A description of the namespace shown to the model. - When returned on a response, this is the effective execution mode. + - `name: string` - - `string` + The namespace name used in tool calls (for example, `crm`). - - `"standard" or "pro"` + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - Controls the reasoning execution mode for the request. + The function/custom tools available inside this namespace. - When returned on a response, this is the effective execution mode. + - `Function object { name, type, allowed_callers, 5 more }` - - `"standard"` + - `name: string` - - `"pro"` + - `type: "function"` - - `summary: optional "auto" or "concise" or "detailed"` + - `"function"` - 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"` + - `defer_loading: optional boolean` -- `text: optional object { format, verbosity }` + Whether this function should be deferred and discovered via tool search. - Configuration options for a text response from the model. Can be plain - text or structured JSON data. Learn more: + - `description: optional string` - - [Text inputs and outputs](/docs/guides/text) - - [Structured Outputs](/docs/guides/structured-outputs) + - `output_schema: optional map[unknown]` - - `format: optional BetaResponseFormatTextConfig` + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - An object specifying the format that the model must output. + - `parameters: optional unknown` - 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). + - `strict: optional boolean` - The default format is `{ "type": "text" }` with no additional options. + 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. - **Not recommended for gpt-4o and newer models:** + - `Custom object { name, type, allowed_callers, 3 more }` - 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. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `Text object { type }` + - `name: string` - Default response format. Used to generate text responses. + The name of the custom tool, used to identify it in tool calls. - - `type: "text"` + - `type: "custom"` - The type of response format being defined. Always `text`. + The type of the custom tool. Always `custom`. - - `"text"` + - `"custom"` - - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` + - `allowed_callers: optional array of "direct" or "programmatic"` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + The tool invocation context(s). - - `name: string` + - `"direct"` - 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. + - `"programmatic"` - - `schema: map[unknown]` + - `defer_loading: optional boolean` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + Whether this tool should be deferred and discovered via tool search. - - `type: "json_schema"` + - `description: optional string` - The type of response format being defined. Always `json_schema`. + Optional description of the custom tool, used to provide more context. - - `"json_schema"` + - `format: optional object { type } or object { definition, syntax, type }` - - `description: optional string` + The input format for the custom tool. Default is unconstrained text. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `Text object { type }` - - `strict: optional boolean` + Unconstrained free-form text. - 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: "text"` - - `JSONObject object { type }` + Unconstrained text format. Always `text`. - 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. + - `"text"` - - `type: "json_object"` + - `Grammar object { definition, syntax, type }` - The type of response format being defined. Always `json_object`. + A grammar defined by the user. - - `"json_object"` + - `definition: string` - - `verbosity: optional "low" or "medium" or "high"` + The grammar definition. - 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`. + - `syntax: "lark" or "regex"` - - `"low"` + The syntax of the grammar definition. One of `lark` or `regex`. - - `"medium"` + - `"lark"` - - `"high"` + - `"regex"` -- `tool_choice: optional BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` + - `type: "grammar"` - Controls which tool the model should use, if any. + Grammar format. Always `grammar`. - - `BetaToolChoiceOptions = "none" or "auto" or "required"` + - `"grammar"` - Controls which (if any) tool is called by the model. + - `type: "namespace"` - `none` means the model will not call any tool and instead generates a message. + The type of the tool. Always `namespace`. - `auto` means the model can pick between generating a message or calling one or - more tools. + - `"namespace"` - `required` means the model must call one or more tools. + - `ToolSearch object { type, description, execution, parameters }` - - `"none"` + Hosted or BYOT tool search configuration for deferred tools. - - `"auto"` + - `type: "tool_search"` - - `"required"` + The type of the tool. Always `tool_search`. - - `BetaToolChoiceAllowed object { mode, tools, type }` + - `"tool_search"` - Constrains the tools available to the model to a pre-defined set. + - `description: optional string` - - `mode: "auto" or "required"` + Description shown to the model for a client-executed tool search tool. - Constrains the tools available to the model to a pre-defined set. + - `execution: optional "server" or "client"` - `auto` allows the model to pick from among the allowed tools and generate a - message. + Whether tool search is executed by the server or by the client. - `required` requires the model to call one or more of the allowed tools. + - `"server"` - - `"auto"` + - `"client"` - - `"required"` + - `parameters: optional unknown` - - `tools: array of map[unknown]` + Parameter schema for a client-executed tool search tool. - A list of tool definitions that the model should be allowed to call. + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - For the Responses API, the list of tool definitions might look like: + 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). - ```json - [ - { "type": "function", "name": "get_weather" }, - { "type": "mcp", "server_label": "deepwiki" }, - { "type": "image_generation" } - ] - ``` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `type: "allowed_tools"` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - Allowed tool configuration type. Always `allowed_tools`. + - `"web_search_preview"` - - `"allowed_tools"` + - `"web_search_preview_2025_03_11"` - - `BetaToolChoiceTypes object { type }` + - `search_content_types: optional array of "text" or "image"` - Indicates that the model should use a built-in tool to generate a response. - [Learn more about built-in tools](/docs/guides/tools). + - `"text"` - - `type: "file_search" or "web_search_preview" or "computer" or 5 more` + - `"image"` - The type of hosted tool the model should to use. Learn more about - [built-in tools](/docs/guides/tools). + - `search_context_size: optional "low" or "medium" or "high"` - Allowed values are: + 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. - - `file_search` - - `web_search_preview` - - `computer` - - `computer_use_preview` - - `computer_use` - - `code_interpreter` - - `image_generation` + - `"low"` - - `"file_search"` + - `"medium"` - - `"web_search_preview"` + - `"high"` - - `"computer"` + - `user_location: optional object { type, city, country, 2 more }` - - `"computer_use_preview"` + The user's location. - - `"computer_use"` + - `type: "approximate"` - - `"web_search_preview_2025_03_11"` + The type of location approximation. Always `approximate`. - - `"image_generation"` + - `"approximate"` - - `"code_interpreter"` + - `city: optional string` - - `BetaToolChoiceFunction object { name, type }` + Free text input for the city of the user, e.g. `San Francisco`. - Use this option to force the model to call a specific function. + - `country: optional string` - - `name: string` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The name of the function to call. + - `region: optional string` - - `type: "function"` + Free text input for the region of the user, e.g. `California`. - For function calling, the type is always `function`. + - `timezone: optional string` - - `"function"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `BetaToolChoiceMcp object { server_label, type, name }` + - `ApplyPatch object { type, allowed_callers }` - Use this option to force the model to call a specific tool on a remote MCP server. + Allows the assistant to create, delete, or update files using unified diffs. - - `server_label: string` + - `type: "apply_patch"` - The label of the MCP server to use. + The type of the tool. Always `apply_patch`. - - `type: "mcp"` + - `"apply_patch"` - For MCP tools, the type is always `mcp`. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"mcp"` + The tool invocation context(s). - - `name: optional string` + - `"direct"` - The name of the tool to call on the server. + - `"programmatic"` - - `BetaToolChoiceCustom object { name, type }` + - `type: "tool_search_output"` - Use this option to force the model to call a specific custom tool. + The type of the item. Always `tool_search_output`. - - `name: string` + - `"tool_search_output"` - The name of the custom tool to call. + - `agent: optional object { agent_name }` - - `type: "custom"` + The agent that produced this item. - For custom tool calling, the type is always `custom`. + - `agent_name: string` - - `"custom"` + The canonical name of the agent that produced this item. - - `BetaSpecificProgrammaticToolCallingParam object { type }` + - `created_by: optional string` - - `type: "programmatic_tool_calling"` + The identifier of the actor that created the item. - The tool to call. Always `programmatic_tool_calling`. + - `AdditionalTools object { id, role, tools, 2 more }` - - `"programmatic_tool_calling"` + - `id: string` - - `BetaToolChoiceApplyPatch object { type }` + The unique ID of the additional tools item. - Forces the model to call the apply_patch tool when executing a tool call. + - `role: "unknown" or "user" or "assistant" or 5 more` - - `type: "apply_patch"` + The role that provided the additional tools. - The tool to call. Always `apply_patch`. + - `"unknown"` - - `"apply_patch"` + - `"user"` - - `BetaToolChoiceShell object { type }` + - `"assistant"` - Forces the model to call the shell tool when a tool call is required. + - `"system"` - - `type: "shell"` + - `"critic"` - The tool to call. Always `shell`. + - `"discriminator"` - - `"shell"` + - `"developer"` -- `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` + - `"tool"` - 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. + - `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 }` @@ -214657,8418 +215632,7443 @@ Returns an object with `object` set to `response.input_tokens` and an `input_tok 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"` - -- `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"` - -### Returns - -- `input_tokens: number` - -- `object: "response.input_tokens"` - - - `"response.input_tokens"` - -### Example - -```http -curl https://api.openai.com/v1/responses/input_tokens \ - -X POST \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` - -#### Response - -```json -{ - "input_tokens": 123, - "object": "response.input_tokens" -} -``` - -### Example - -```http -curl -X POST https://api.openai.com/v1/responses/input_tokens \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "model": "gpt-5", - "input": "Tell me a joke." - }' -``` - -#### Response - -```json -{ - "object": "response.input_tokens", - "input_tokens": 11 -} -``` - -## Domain Types - -### Input Token Count Response - -- `InputTokenCountResponse object { input_tokens, object }` - - - `input_tokens: number` - - - `object: "response.input_tokens"` - - - `"response.input_tokens"` - -# ChatKit - -## Domain Types - -### ChatKit Workflow - -- `ChatKitWorkflow object { id, state_variables, tracing, version }` - - Workflow metadata and state returned for the session. - - - `id: string` - - Identifier of the workflow backing the session. - - - `state_variables: map[string or boolean or number]` - - State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. - - - `string` - - - `boolean` - - - `number` - - - `tracing: object { enabled }` - - Tracing settings applied to the workflow. - - - `enabled: boolean` - - Indicates whether tracing is enabled. - - - `version: string` - - Specific workflow version used for the session. Defaults to null when using the latest deployment. - -# Sessions - -## Cancel chat session - -**post** `/chatkit/sessions/{session_id}/cancel` - -Cancel an active ChatKit session and return its most recent metadata. - -Cancelling prevents new requests from using the issued client secret. - -### Path Parameters - -- `session_id: string` - -### Returns - -- `ChatSession object { id, chatkit_configuration, client_secret, 7 more }` - - Represents a ChatKit session and its resolved configuration. - - - `id: string` - - Identifier for the ChatKit session. - - - `chatkit_configuration: ChatSessionChatKitConfiguration` - - Resolved ChatKit feature configuration for the session. - - - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` - - Automatic thread titling preferences. - - - `enabled: boolean` - - Whether automatic thread titling is enabled. - - - `file_upload: ChatSessionFileUpload` - - Upload settings for the session. - - - `enabled: boolean` - - Indicates if uploads are enabled for the session. - - - `max_file_size: number` - - Maximum upload size in megabytes. - - - `max_files: number` - - Maximum number of uploads allowed during the session. - - - `history: ChatSessionHistory` - - History retention configuration. - - - `enabled: boolean` - - Indicates if chat history is persisted for the session. - - - `recent_threads: number` - - Number of prior threads surfaced in history views. Defaults to null when all history is retained. - - - `client_secret: string` - - Ephemeral client secret that authenticates session requests. - - - `expires_at: number` - - Unix timestamp (in seconds) for when the session expires. - - - `max_requests_per_1_minute: number` - - Convenience copy of the per-minute request limit. - - - `object: "chatkit.session"` - - Type discriminator that is always `chatkit.session`. - - - `"chatkit.session"` - - - `rate_limits: ChatSessionRateLimits` - - Resolved rate limit values. - - - `max_requests_per_1_minute: number` - - Maximum allowed requests per one-minute window. - - - `status: ChatSessionStatus` - - Current lifecycle state of the session. - - - `"active"` - - - `"expired"` - - - `"cancelled"` - - - `user: string` - - User identifier associated with the session. - - - `workflow: ChatKitWorkflow` - - Workflow metadata for the session. - - - `id: string` - - Identifier of the workflow backing the session. - - - `state_variables: map[string or boolean or number]` - - State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. - - - `string` - - - `boolean` - - - `number` - - - `tracing: object { enabled }` - - Tracing settings applied to the workflow. - - - `enabled: boolean` - - Indicates whether tracing is enabled. - - - `version: string` - - Specific workflow version used for the session. Defaults to null when using the latest deployment. - -### Example - -```http -curl https://api.openai.com/v1/chatkit/sessions/$SESSION_ID/cancel \ - -X POST \ - -H 'OpenAI-Beta: chatkit_beta=v1' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` - -#### Response - -```json -{ - "id": "id", - "chatkit_configuration": { - "automatic_thread_titling": { - "enabled": true - }, - "file_upload": { - "enabled": true, - "max_file_size": 0, - "max_files": 0 - }, - "history": { - "enabled": true, - "recent_threads": 0 - } - }, - "client_secret": "client_secret", - "expires_at": 0, - "max_requests_per_1_minute": 0, - "object": "chatkit.session", - "rate_limits": { - "max_requests_per_1_minute": 0 - }, - "status": "active", - "user": "user", - "workflow": { - "id": "id", - "state_variables": { - "foo": "string" - }, - "tracing": { - "enabled": true - }, - "version": "version" - } -} -``` - -### Example - -```http -curl -X POST \ - https://api.openai.com/v1/chatkit/sessions/cksess_123/cancel \ - -H "OpenAI-Beta: chatkit_beta=v1" \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` - -#### Response - -```json -{ - "id": "cksess_123", - "object": "chatkit.session", - "workflow": { - "id": "workflow_alpha", - "version": "1" - }, - "scope": { - "customer_id": "cust_456" - }, - "max_requests_per_1_minute": 30, - "ttl_seconds": 900, - "status": "cancelled", - "cancelled_at": 1712345678 -} -``` - -## Create ChatKit session - -**post** `/chatkit/sessions` - -Create a ChatKit session. - -### Body Parameters - -- `user: string` - - A free-form string that identifies your end user; ensures this Session can access other objects that have the same `user` scope. - -- `workflow: ChatSessionWorkflowParam` - - Workflow that powers the session. - - - `id: string` - - Identifier for the workflow invoked by the session. - - - `state_variables: optional map[string or boolean or number]` - - State variables forwarded to the workflow. Keys may be up to 64 characters, values must be primitive types, and the map defaults to an empty object. - - - `string` - - - `boolean` - - - `number` - - - `tracing: optional object { enabled }` - - Optional tracing overrides for the workflow invocation. When omitted, tracing is enabled by default. - - - `enabled: optional boolean` - - Whether tracing is enabled during the session. Defaults to true. - - - `version: optional string` - - Specific workflow version to run. Defaults to the latest deployed version. - -- `chatkit_configuration: optional ChatSessionChatKitConfigurationParam` - - Optional overrides for ChatKit runtime configuration features - - - `automatic_thread_titling: optional object { enabled }` - - Configuration for automatic thread titling. When omitted, automatic thread titling is enabled by default. - - - `enabled: optional boolean` - - Enable automatic thread title generation. Defaults to true. - - - `file_upload: optional object { enabled, max_file_size, max_files }` - - Configuration for upload enablement and limits. When omitted, uploads are disabled by default (max_files 10, max_file_size 512 MB). - - - `enabled: optional boolean` - - Enable uploads for this session. Defaults to false. - - - `max_file_size: optional number` + - `type: "approximate"` - Maximum size in megabytes for each uploaded file. Defaults to 512 MB, which is the maximum allowable size. + The type of location approximation. Always `approximate`. - - `max_files: optional number` + - `"approximate"` - Maximum number of files that can be uploaded to the session. Defaults to 10. + - `city: optional string` - - `history: optional object { enabled, recent_threads }` + Free text input for the city of the user, e.g. `San Francisco`. - Configuration for chat history retention. When omitted, history is enabled by default with no limit on recent_threads (null). + - `country: optional string` - - `enabled: optional boolean` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - Enables chat users to access previous ChatKit threads. Defaults to true. + - `region: optional string` - - `recent_threads: optional number` + Free text input for the region of the user, e.g. `California`. - Number of recent ChatKit threads users have access to. Defaults to unlimited when unset. + - `timezone: optional string` -- `expires_after: optional ChatSessionExpiresAfterParam` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - Optional override for session expiration timing in seconds from creation. Defaults to 10 minutes. + - `ApplyPatch object { type, allowed_callers }` - - `anchor: "created_at"` + Allows the assistant to create, delete, or update files using unified diffs. - Base timestamp used to calculate expiration. Currently fixed to `created_at`. + - `type: "apply_patch"` - - `"created_at"` + The type of the tool. Always `apply_patch`. - - `seconds: number` + - `"apply_patch"` - Number of seconds after the anchor when the session expires. + - `allowed_callers: optional array of "direct" or "programmatic"` -- `rate_limits: optional ChatSessionRateLimitsParam` + The tool invocation context(s). - Optional override for per-minute request limits. When omitted, defaults to 10. + - `"direct"` - - `max_requests_per_1_minute: optional number` + - `"programmatic"` - Maximum number of requests allowed per minute for the session. Defaults to 10. + - `type: "additional_tools"` -### Returns + The type of the item. Always `additional_tools`. -- `ChatSession object { id, chatkit_configuration, client_secret, 7 more }` + - `"additional_tools"` - Represents a ChatKit session and its resolved configuration. + - `agent: optional object { agent_name }` - - `id: string` + The agent that produced this item. - Identifier for the ChatKit session. + - `agent_name: string` - - `chatkit_configuration: ChatSessionChatKitConfiguration` + The canonical name of the agent that produced this item. - Resolved ChatKit feature configuration for the session. + - `Reasoning object { id, summary, type, 4 more }` - - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` + 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). - Automatic thread titling preferences. + - `id: string` - - `enabled: boolean` + The unique identifier of the reasoning content. - Whether automatic thread titling is enabled. + - `summary: array of object { text, type }` - - `file_upload: ChatSessionFileUpload` + Reasoning summary content. - Upload settings for the session. + - `text: string` - - `enabled: boolean` + A summary of the reasoning output from the model so far. - Indicates if uploads are enabled for the session. + - `type: "summary_text"` - - `max_file_size: number` + The type of the object. Always `summary_text`. - Maximum upload size in megabytes. + - `"summary_text"` - - `max_files: number` + - `type: "reasoning"` - Maximum number of uploads allowed during the session. + The type of the object. Always `reasoning`. - - `history: ChatSessionHistory` + - `"reasoning"` - History retention configuration. + - `agent: optional object { agent_name }` - - `enabled: boolean` + The agent that produced this item. - Indicates if chat history is persisted for the session. + - `agent_name: string` - - `recent_threads: number` + The canonical name of the agent that produced this item. - Number of prior threads surfaced in history views. Defaults to null when all history is retained. + - `content: optional array of object { text, type }` - - `client_secret: string` + Reasoning text content. - Ephemeral client secret that authenticates session requests. + - `text: string` - - `expires_at: number` + The reasoning text from the model. - Unix timestamp (in seconds) for when the session expires. + - `type: "reasoning_text"` - - `max_requests_per_1_minute: number` + The type of the reasoning text. Always `reasoning_text`. - Convenience copy of the per-minute request limit. + - `"reasoning_text"` - - `object: "chatkit.session"` + - `encrypted_content: optional string` - Type discriminator that is always `chatkit.session`. + 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. - - `"chatkit.session"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `rate_limits: ChatSessionRateLimits` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Resolved rate limit values. + - `"in_progress"` - - `max_requests_per_1_minute: number` + - `"completed"` - Maximum allowed requests per one-minute window. + - `"incomplete"` - - `status: ChatSessionStatus` + - `Program object { id, call_id, code, 3 more }` - Current lifecycle state of the session. + - `id: string` - - `"active"` + The unique ID of the program item. - - `"expired"` + - `call_id: string` - - `"cancelled"` + The stable call ID of the program item. - - `user: string` + - `code: string` - User identifier associated with the session. + The JavaScript source executed by programmatic tool calling. - - `workflow: ChatKitWorkflow` + - `fingerprint: string` - Workflow metadata for the session. + Opaque program replay fingerprint that must be round-tripped. - - `id: string` + - `type: "program"` - Identifier of the workflow backing the session. + The type of the item. Always `program`. - - `state_variables: map[string or boolean or number]` + - `"program"` - State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. + - `agent: optional object { agent_name }` - - `string` + The agent that produced this item. - - `boolean` + - `agent_name: string` - - `number` + The canonical name of the agent that produced this item. - - `tracing: object { enabled }` + - `ProgramOutput object { id, call_id, result, 3 more }` - Tracing settings applied to the workflow. + - `id: string` - - `enabled: boolean` + The unique ID of the program output item. - Indicates whether tracing is enabled. + - `call_id: string` - - `version: string` + The call ID of the program item. - Specific workflow version used for the session. Defaults to null when using the latest deployment. + - `result: string` -### Example + The result produced by the program item. -```http -curl https://api.openai.com/v1/chatkit/sessions \ - -H 'Content-Type: application/json' \ - -H 'OpenAI-Beta: chatkit_beta=v1' \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "user": "x", - "workflow": { - "id": "id" - } - }' -``` + - `status: "completed" or "incomplete"` -#### Response + The terminal status of the program output item. -```json -{ - "id": "id", - "chatkit_configuration": { - "automatic_thread_titling": { - "enabled": true - }, - "file_upload": { - "enabled": true, - "max_file_size": 0, - "max_files": 0 - }, - "history": { - "enabled": true, - "recent_threads": 0 - } - }, - "client_secret": "client_secret", - "expires_at": 0, - "max_requests_per_1_minute": 0, - "object": "chatkit.session", - "rate_limits": { - "max_requests_per_1_minute": 0 - }, - "status": "active", - "user": "user", - "workflow": { - "id": "id", - "state_variables": { - "foo": "string" - }, - "tracing": { - "enabled": true - }, - "version": "version" - } -} -``` + - `"completed"` -### Example + - `"incomplete"` -```http -curl https://api.openai.com/v1/chatkit/sessions \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: chatkit_beta=v1" \ - -d '{ - "workflow": { - "id": "workflow_alpha", - "version": "2024-10-01" - }, - "scope": { - "project": "alpha", - "environment": "staging" - }, - "expires_after": 1800, - "max_requests_per_1_minute": 60, - "max_requests_per_session": 500 - }' -``` + - `type: "program_output"` -#### Response + The type of the item. Always `program_output`. -```json -{ - "client_secret": "chatkit_token_123", - "expires_at": 1735689600, - "workflow": { - "id": "workflow_alpha", - "version": "2024-10-01" - }, - "scope": { - "project": "alpha", - "environment": "staging" - }, - "max_requests_per_1_minute": 60, - "max_requests_per_session": 500, - "status": "active" -} -``` + - `"program_output"` -# Threads + - `agent: optional object { agent_name }` -## List ChatKit thread items + The agent that produced this item. -**get** `/chatkit/threads/{thread_id}/items` + - `agent_name: string` -List items that belong to a ChatKit thread. + The canonical name of the agent that produced this item. -### Path Parameters + - `Compaction object { id, encrypted_content, type, 2 more }` -- `thread_id: string` + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). -### Query Parameters + - `id: string` -- `after: optional string` + The unique ID of the compaction item. - List items created after this thread item ID. Defaults to null for the first page. + - `encrypted_content: string` -- `before: optional string` + The encrypted content that was produced by compaction. - List items created before this thread item ID. Defaults to null for the newest results. + - `type: "compaction"` -- `limit: optional number` + The type of the item. Always `compaction`. - Maximum number of thread items to return. Defaults to 20. + - `"compaction"` -- `order: optional "asc" or "desc"` + - `agent: optional object { agent_name }` - Sort order for results by creation time. Defaults to `desc`. + The agent that produced this item. - - `"asc"` + - `agent_name: string` - - `"desc"` + The canonical name of the agent that produced this item. -### Returns + - `created_by: optional string` -- `ChatKitThreadItemList object { data, first_id, has_more, 2 more }` + The identifier of the actor that created the item. - A paginated list of thread items rendered for the ChatKit API. + - `ImageGenerationCall object { id, result, status, 2 more }` - - `data: array of ChatKitThreadUserMessageItem or ChatKitThreadAssistantMessageItem or ChatKitWidgetItem or 3 more` + An image generation request made by the model. - A list of items + - `id: string` - - `ChatKitThreadUserMessageItem object { id, attachments, content, 5 more }` + The unique ID of the image generation call. - User-authored messages within a thread. + - `result: string` - - `id: string` + The generated image encoded in base64. - Identifier of the thread item. + - `status: "in_progress" or "completed" or "generating" or "failed"` - - `attachments: array of ChatKitAttachment` + The status of the image generation call. - Attachments associated with the user message. Defaults to an empty list. + - `"in_progress"` - - `id: string` + - `"completed"` - Identifier for the attachment. + - `"generating"` - - `mime_type: string` + - `"failed"` - MIME type of the attachment. + - `type: "image_generation_call"` - - `name: string` + The type of the image generation call. Always `image_generation_call`. - Original display name for the attachment. + - `"image_generation_call"` - - `preview_url: string` + - `agent: optional object { agent_name }` - Preview URL for rendering the attachment inline. + The agent that produced this item. - - `type: "image" or "file"` + - `agent_name: string` - Attachment discriminator. + The canonical name of the agent that produced this item. - - `"image"` + - `CodeInterpreterCall object { id, code, container_id, 4 more }` - - `"file"` + A tool call to run code. - - `content: array of object { text, type } or object { text, type }` + - `id: string` - Ordered content elements supplied by the user. + The unique ID of the code interpreter tool call. - - `InputText object { text, type }` + - `code: string` - Text block that a user contributed to the thread. + The code to run, or null if not available. - - `text: string` + - `container_id: string` - Plain-text content supplied by the user. + The ID of the container used to run the code. - - `type: "input_text"` + - `outputs: array of object { logs, type } or object { type, url }` - Type discriminator that is always `input_text`. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `"input_text"` + - `Logs object { logs, type }` - - `QuotedText object { text, type }` + The logs output from the code interpreter. - Quoted snippet that the user referenced in their message. + - `logs: string` - - `text: string` + The logs output from the code interpreter. - Quoted text content. + - `type: "logs"` - - `type: "quoted_text"` + The type of the output. Always `logs`. - Type discriminator that is always `quoted_text`. + - `"logs"` - - `"quoted_text"` + - `Image object { type, url }` - - `created_at: number` + The image output from the code interpreter. - Unix timestamp (in seconds) for when the item was created. + - `type: "image"` - - `inference_options: object { model, tool_choice }` + The type of the output. Always `image`. - Inference overrides applied to the message. Defaults to null when unset. + - `"image"` - - `model: string` + - `url: string` - Model name that generated the response. Defaults to null when using the session default. + The URL of the image output from the code interpreter. - - `tool_choice: object { id }` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - Preferred tool to invoke. Defaults to null when ChatKit should auto-select. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `id: string` + - `"in_progress"` - Identifier of the requested tool. + - `"completed"` - - `object: "chatkit.thread_item"` + - `"incomplete"` - Type discriminator that is always `chatkit.thread_item`. + - `"interpreting"` - - `"chatkit.thread_item"` + - `"failed"` - - `thread_id: string` + - `type: "code_interpreter_call"` - Identifier of the parent thread. + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `type: "chatkit.user_message"` + - `"code_interpreter_call"` - - `"chatkit.user_message"` + - `agent: optional object { agent_name }` - - `ChatKitThreadAssistantMessageItem object { id, content, created_at, 3 more }` + The agent that produced this item. - Assistant-authored message within a thread. + - `agent_name: string` - - `id: string` + The canonical name of the agent that produced this item. - Identifier of the thread item. + - `LocalShellCall object { id, action, call_id, 3 more }` - - `content: array of ChatKitResponseOutputText` + A tool call to run a command on the local shell. - Ordered assistant response segments. + - `id: string` - - `annotations: array of object { source, type } or object { source, type }` + The unique ID of the local shell call. - Ordered list of annotations attached to the response text. + - `action: object { command, env, type, 3 more }` - - `File object { source, type }` + Execute a shell command on the server. - Annotation that references an uploaded file. + - `command: array of string` - - `source: object { filename, type }` + The command to run. - File attachment referenced by the annotation. + - `env: map[string]` - - `filename: string` + Environment variables to set for the command. - Filename referenced by the annotation. + - `type: "exec"` - - `type: "file"` + The type of the local shell action. Always `exec`. - Type discriminator that is always `file`. + - `"exec"` - - `"file"` + - `timeout_ms: optional number` - - `type: "file"` + Optional timeout in milliseconds for the command. - Type discriminator that is always `file` for this annotation. + - `user: optional string` - - `"file"` + Optional user to run the command as. - - `URL object { source, type }` + - `working_directory: optional string` - Annotation that references a URL. + Optional working directory to run the command in. - - `source: object { type, url }` + - `call_id: string` - URL referenced by the annotation. + The unique ID of the local shell tool call generated by the model. - - `type: "url"` + - `status: "in_progress" or "completed" or "incomplete"` - Type discriminator that is always `url`. + The status of the local shell call. - - `"url"` + - `"in_progress"` - - `url: string` + - `"completed"` - URL referenced by the annotation. + - `"incomplete"` - - `type: "url"` + - `type: "local_shell_call"` - Type discriminator that is always `url` for this annotation. + The type of the local shell call. Always `local_shell_call`. - - `"url"` + - `"local_shell_call"` - - `text: string` + - `agent: optional object { agent_name }` - Assistant generated text. + The agent that produced this item. - - `type: "output_text"` + - `agent_name: string` - Type discriminator that is always `output_text`. + The canonical name of the agent that produced this item. - - `"output_text"` + - `LocalShellCallOutput object { id, output, type, 2 more }` - - `created_at: number` + The output of a local shell tool call. - Unix timestamp (in seconds) for when the item was created. + - `id: string` - - `object: "chatkit.thread_item"` + The unique ID of the local shell tool call generated by the model. - Type discriminator that is always `chatkit.thread_item`. + - `output: string` - - `"chatkit.thread_item"` + A JSON string of the output of the local shell tool call. - - `thread_id: string` + - `type: "local_shell_call_output"` - Identifier of the parent thread. + The type of the local shell tool call output. Always `local_shell_call_output`. - - `type: "chatkit.assistant_message"` + - `"local_shell_call_output"` - Type discriminator that is always `chatkit.assistant_message`. + - `agent: optional object { agent_name }` - - `"chatkit.assistant_message"` + The agent that produced this item. - - `ChatKitWidgetItem object { id, created_at, object, 3 more }` + - `agent_name: string` - Thread item that renders a widget payload. + The canonical name of the agent that produced this item. - - `id: string` + - `status: optional "in_progress" or "completed" or "incomplete"` - Identifier of the thread item. + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `created_at: number` + - `"in_progress"` - Unix timestamp (in seconds) for when the item was created. + - `"completed"` - - `object: "chatkit.thread_item"` + - `"incomplete"` - Type discriminator that is always `chatkit.thread_item`. + - `ShellCall object { id, action, call_id, 6 more }` - - `"chatkit.thread_item"` + A tool call that executes one or more shell commands in a managed environment. - - `thread_id: string` + - `id: string` - Identifier of the parent thread. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `type: "chatkit.widget"` + - `action: object { commands, max_output_length, timeout_ms }` - Type discriminator that is always `chatkit.widget`. + The shell commands and limits that describe how to run the tool call. - - `"chatkit.widget"` + - `commands: array of string` - - `widget: string` + - `max_output_length: number` - Serialized widget payload rendered in the UI. + Optional maximum number of characters to return from each command. - - `ChatKitClientToolCall object { id, arguments, call_id, 7 more }` + - `timeout_ms: number` - Record of a client side tool invocation initiated by the assistant. + Optional timeout in milliseconds for the commands. - - `id: string` + - `call_id: string` - Identifier of the thread item. + The unique ID of the shell tool call generated by the model. - - `arguments: string` + - `environment: BetaResponseLocalEnvironment or BetaResponseContainerReference` - JSON-encoded arguments that were sent to the tool. + Represents the use of a local environment to perform shell actions. - - `call_id: string` + - `BetaResponseLocalEnvironment object { type }` - Identifier for the client tool call. + Represents the use of a local environment to perform shell actions. - - `created_at: number` + - `type: "local"` - Unix timestamp (in seconds) for when the item was created. + The environment type. Always `local`. - - `name: string` + - `"local"` - Tool name that was invoked. + - `BetaResponseContainerReference object { container_id, type }` - - `object: "chatkit.thread_item"` + Represents a container created with /v1/containers. - Type discriminator that is always `chatkit.thread_item`. + - `container_id: string` - - `"chatkit.thread_item"` + - `type: "container_reference"` - - `output: string` + The environment type. Always `container_reference`. - JSON-encoded output captured from the tool. Defaults to null while execution is in progress. + - `"container_reference"` - - `status: "in_progress" or "completed"` + - `status: "in_progress" or "completed" or "incomplete"` - Execution status for the tool call. + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - `"in_progress"` - `"completed"` - - `thread_id: string` + - `"incomplete"` - Identifier of the parent thread. + - `type: "shell_call"` - - `type: "chatkit.client_tool_call"` + The type of the item. Always `shell_call`. - Type discriminator that is always `chatkit.client_tool_call`. + - `"shell_call"` - - `"chatkit.client_tool_call"` + - `agent: optional object { agent_name }` - - `ChatKitTask object { id, created_at, heading, 5 more }` + The agent that produced this item. - Task emitted by the workflow to show progress and status updates. + - `agent_name: string` - - `id: string` + The canonical name of the agent that produced this item. - Identifier of the thread item. + - `caller: optional object { type } or object { caller_id, type }` - - `created_at: number` + The execution context that produced this tool call. - Unix timestamp (in seconds) for when the item was created. + - `Direct object { type }` - - `heading: string` + - `type: "direct"` - Optional heading for the task. Defaults to null when not provided. + - `"direct"` - - `object: "chatkit.thread_item"` + - `Program object { caller_id, type }` - Type discriminator that is always `chatkit.thread_item`. + - `caller_id: string` - - `"chatkit.thread_item"` + The call ID of the program item that produced this tool call. - - `summary: string` + - `type: "program"` - Optional summary that describes the task. Defaults to null when omitted. + - `"program"` - - `task_type: "custom" or "thought"` + - `created_by: optional string` - Subtype for the task. + The ID of the entity that created this tool call. - - `"custom"` + - `ShellCallOutput object { id, call_id, max_output_length, 6 more }` - - `"thought"` + The output of a shell tool call that was emitted. - - `thread_id: string` + - `id: string` - Identifier of the parent thread. + The unique ID of the shell call output. Populated when this item is returned via API. - - `type: "chatkit.task"` + - `call_id: string` - Type discriminator that is always `chatkit.task`. + The unique ID of the shell tool call generated by the model. - - `"chatkit.task"` + - `max_output_length: number` - - `ChatKitTaskGroup object { id, created_at, object, 3 more }` + The maximum length of the shell command output. This is generated by the model and should be passed back with the raw output. - Collection of workflow tasks grouped together in the thread. + - `output: array of object { outcome, stderr, stdout, created_by }` - - `id: string` + An array of shell call output contents - Identifier of the thread item. + - `outcome: object { type } or object { exit_code, type }` - - `created_at: number` + Represents either an exit outcome (with an exit code) or a timeout outcome for a shell call output chunk. - Unix timestamp (in seconds) for when the item was created. + - `Timeout object { type }` - - `object: "chatkit.thread_item"` + Indicates that the shell call exceeded its configured time limit. - Type discriminator that is always `chatkit.thread_item`. + - `type: "timeout"` - - `"chatkit.thread_item"` + The outcome type. Always `timeout`. - - `tasks: array of object { heading, summary, type }` + - `"timeout"` - Tasks included in the group. + - `Exit object { exit_code, type }` - - `heading: string` + Indicates that the shell commands finished and returned an exit code. - Optional heading for the grouped task. Defaults to null when not provided. + - `exit_code: number` - - `summary: string` + Exit code from the shell process. - Optional summary that describes the grouped task. Defaults to null when omitted. + - `type: "exit"` - - `type: "custom" or "thought"` + The outcome type. Always `exit`. - Subtype for the grouped task. + - `"exit"` - - `"custom"` + - `stderr: string` - - `"thought"` + The standard error output that was captured. - - `thread_id: string` + - `stdout: string` - Identifier of the parent thread. + The standard output that was captured. - - `type: "chatkit.task_group"` + - `created_by: optional string` - Type discriminator that is always `chatkit.task_group`. + The identifier of the actor that created the item. - - `"chatkit.task_group"` + - `status: "in_progress" or "completed" or "incomplete"` - - `first_id: string` + The status of the shell call output. One of `in_progress`, `completed`, or `incomplete`. - The ID of the first item in the list. + - `"in_progress"` - - `has_more: boolean` + - `"completed"` - Whether there are more items available. + - `"incomplete"` - - `last_id: string` + - `type: "shell_call_output"` - The ID of the last item in the list. + The type of the shell call output. Always `shell_call_output`. - - `object: "list"` + - `"shell_call_output"` - The type of object returned, must be `list`. + - `agent: optional object { agent_name }` - - `"list"` + The agent that produced this item. -### Example + - `agent_name: string` -```http -curl https://api.openai.com/v1/chatkit/threads/$THREAD_ID/items \ - -H 'OpenAI-Beta: chatkit_beta=v1' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + The canonical name of the agent that produced this item. -#### Response + - `caller: optional object { type } or object { caller_id, type }` -```json -{ - "data": [ - { - "id": "id", - "attachments": [ - { - "id": "id", - "mime_type": "mime_type", - "name": "name", - "preview_url": "https://example.com", - "type": "image" - } - ], - "content": [ - { - "text": "text", - "type": "input_text" - } - ], - "created_at": 0, - "inference_options": { - "model": "model", - "tool_choice": { - "id": "id" - } - }, - "object": "chatkit.thread_item", - "thread_id": "thread_id", - "type": "chatkit.user_message" - } - ], - "first_id": "first_id", - "has_more": true, - "last_id": "last_id", - "object": "list" -} -``` + The execution context that produced this tool call. -### Example + - `Direct object { type }` -```http -curl "https://api.openai.com/v1/chatkit/threads/cthr_abc123/items?limit=3" \ - -H "OpenAI-Beta: chatkit_beta=v1" \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `type: "direct"` -#### Response + - `"direct"` -```json -{ - "data": [ - { - "id": "cthi_user_001", - "object": "chatkit.thread_item", - "type": "user_message", - "content": [ - { - "type": "input_text", - "text": "I need help debugging an onboarding issue." - } - ], - "attachments": [] - }, - { - "id": "cthi_assistant_002", - "object": "chatkit.thread_item", - "type": "assistant_message", - "content": [ - { - "type": "output_text", - "text": "Let's start by confirming the workflow version you deployed." - } - ] - } - ], - "has_more": false, - "object": "list" -} -``` + - `Program object { caller_id, type }` -## Retrieve ChatKit thread + - `caller_id: string` -**get** `/chatkit/threads/{thread_id}` + The call ID of the program item that produced this tool call. -Retrieve a ChatKit thread by its identifier. + - `type: "program"` -### Path Parameters + - `"program"` -- `thread_id: string` + - `created_by: optional string` -### Returns + The identifier of the actor that created the item. -- `ChatKitThread object { id, created_at, object, 3 more }` + - `ApplyPatchCall object { id, call_id, operation, 5 more }` - Represents a ChatKit thread and its current status. + A tool call that applies file diffs by creating, deleting, or updating files. - `id: string` - Identifier of the thread. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `created_at: number` + - `call_id: string` - Unix timestamp (in seconds) for when the thread was created. + The unique ID of the apply patch tool call generated by the model. - - `object: "chatkit.thread"` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - Type discriminator that is always `chatkit.thread`. + One of the create_file, delete_file, or update_file operations applied via apply_patch. - - `"chatkit.thread"` + - `CreateFile object { diff, path, type }` - - `status: object { type } or object { reason, type } or object { reason, type }` + Instruction describing how to create a file via the apply_patch tool. - Current status for the thread. Defaults to `active` for newly created threads. + - `diff: string` - - `Active object { type }` + Diff to apply. - Indicates that a thread is active. + - `path: string` - - `type: "active"` + Path of the file to create. - Status discriminator that is always `active`. + - `type: "create_file"` - - `"active"` + Create a new file with the provided diff. - - `Locked object { reason, type }` + - `"create_file"` - Indicates that a thread is locked and cannot accept new input. + - `DeleteFile object { path, type }` - - `reason: string` + Instruction describing how to delete a file via the apply_patch tool. - Reason that the thread was locked. Defaults to null when no reason is recorded. + - `path: string` - - `type: "locked"` + Path of the file to delete. - Status discriminator that is always `locked`. + - `type: "delete_file"` - - `"locked"` + Delete the specified file. - - `Closed object { reason, type }` + - `"delete_file"` - Indicates that a thread has been closed. + - `UpdateFile object { diff, path, type }` - - `reason: string` + Instruction describing how to update a file via the apply_patch tool. - Reason that the thread was closed. Defaults to null when no reason is recorded. + - `diff: string` - - `type: "closed"` + Diff to apply. - Status discriminator that is always `closed`. + - `path: string` - - `"closed"` + Path of the file to update. - - `title: string` + - `type: "update_file"` - Optional human-readable title for the thread. Defaults to null when no title has been generated. + Update an existing file with the provided diff. - - `user: string` + - `"update_file"` - Free-form string that identifies your end user who owns the thread. + - `status: "in_progress" or "completed"` -### Example + The status of the apply patch tool call. One of `in_progress` or `completed`. -```http -curl https://api.openai.com/v1/chatkit/threads/$THREAD_ID \ - -H 'OpenAI-Beta: chatkit_beta=v1' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `"in_progress"` -#### Response + - `"completed"` -```json -{ - "id": "cthr_def456", - "created_at": 1712345600, - "object": "chatkit.thread", - "status": { - "type": "active" - }, - "title": "Demo feedback", - "user": "user_456" -} -``` + - `type: "apply_patch_call"` -### Example + The type of the item. Always `apply_patch_call`. -```http -curl https://api.openai.com/v1/chatkit/threads/cthr_abc123 \ - -H "OpenAI-Beta: chatkit_beta=v1" \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `"apply_patch_call"` -#### Response + - `agent: optional object { agent_name }` -```json -{ - "id": "cthr_abc123", - "object": "chatkit.thread", - "title": "Customer escalation", - "items": { - "data": [ - { - "id": "cthi_user_001", - "object": "chatkit.thread_item", - "type": "user_message", - "content": [ - { - "type": "input_text", - "text": "I need help debugging an onboarding issue." - } - ], - "attachments": [] - }, - { - "id": "cthi_assistant_002", - "object": "chatkit.thread_item", - "type": "assistant_message", - "content": [ - { - "type": "output_text", - "text": "Let's start by confirming the workflow version you deployed." - } - ] - } - ], - "has_more": false - } -} -``` + The agent that produced this item. -## Delete ChatKit thread + - `agent_name: string` -**delete** `/chatkit/threads/{thread_id}` + The canonical name of the agent that produced this item. -Delete a ChatKit thread along with its items and stored attachments. + - `caller: optional object { type } or object { caller_id, type }` -### Path Parameters + The execution context that produced this tool call. -- `thread_id: string` + - `Direct object { type }` -### Returns + - `type: "direct"` -- `id: string` + - `"direct"` - Identifier of the deleted thread. + - `Program object { caller_id, type }` -- `deleted: boolean` + - `caller_id: string` - Indicates that the thread has been deleted. + The call ID of the program item that produced this tool call. -- `object: "chatkit.thread.deleted"` + - `type: "program"` - Type discriminator that is always `chatkit.thread.deleted`. + - `"program"` - - `"chatkit.thread.deleted"` + - `created_by: optional string` -### Example + The ID of the entity that created this tool call. -```http -curl https://api.openai.com/v1/chatkit/threads/$THREAD_ID \ - -X DELETE \ - -H 'OpenAI-Beta: chatkit_beta=v1' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `ApplyPatchCallOutput object { id, call_id, status, 5 more }` -#### Response + The output emitted by an apply patch tool call. -```json -{ - "id": "id", - "deleted": true, - "object": "chatkit.thread.deleted" -} -``` + - `id: string` -## List ChatKit threads + The unique ID of the apply patch tool call output. Populated when this item is returned via API. -**get** `/chatkit/threads` + - `call_id: string` -List ChatKit threads with optional pagination and user filters. + The unique ID of the apply patch tool call generated by the model. -### Query Parameters + - `status: "completed" or "failed"` -- `after: optional string` + The status of the apply patch tool call output. One of `completed` or `failed`. - List items created after this thread item ID. Defaults to null for the first page. + - `"completed"` -- `before: optional string` + - `"failed"` - List items created before this thread item ID. Defaults to null for the newest results. + - `type: "apply_patch_call_output"` -- `limit: optional number` + The type of the item. Always `apply_patch_call_output`. - Maximum number of thread items to return. Defaults to 20. + - `"apply_patch_call_output"` -- `order: optional "asc" or "desc"` + - `agent: optional object { agent_name }` - Sort order for results by creation time. Defaults to `desc`. + The agent that produced this item. - - `"asc"` + - `agent_name: string` - - `"desc"` + The canonical name of the agent that produced this item. -- `user: optional string` + - `caller: optional object { type } or object { caller_id, type }` - Filter threads that belong to this user identifier. Defaults to null to return all users. + The execution context that produced this tool call. -### Returns + - `Direct object { type }` -- `data: array of ChatKitThread` + - `type: "direct"` - A list of items + - `"direct"` - - `id: string` + - `Program object { caller_id, type }` - Identifier of the thread. + - `caller_id: string` - - `created_at: number` + The call ID of the program item that produced this tool call. - Unix timestamp (in seconds) for when the thread was created. + - `type: "program"` - - `object: "chatkit.thread"` + - `"program"` - Type discriminator that is always `chatkit.thread`. + - `created_by: optional string` - - `"chatkit.thread"` + The ID of the entity that created this tool call output. - - `status: object { type } or object { reason, type } or object { reason, type }` + - `output: optional string` - Current status for the thread. Defaults to `active` for newly created threads. + Optional textual output returned by the apply patch tool. - - `Active object { type }` + - `McpListTools object { id, server_label, tools, 3 more }` - Indicates that a thread is active. + A list of tools available on an MCP server. - - `type: "active"` + - `id: string` - Status discriminator that is always `active`. + The unique ID of the list. - - `"active"` + - `server_label: string` - - `Locked object { reason, type }` + The label of the MCP server. - Indicates that a thread is locked and cannot accept new input. + - `tools: array of object { input_schema, name, annotations, description }` - - `reason: string` + The tools available on the server. - Reason that the thread was locked. Defaults to null when no reason is recorded. + - `input_schema: unknown` - - `type: "locked"` + The JSON schema describing the tool's input. - Status discriminator that is always `locked`. + - `name: string` - - `"locked"` + The name of the tool. - - `Closed object { reason, type }` + - `annotations: optional unknown` - Indicates that a thread has been closed. + Additional annotations about the tool. - - `reason: string` + - `description: optional string` - Reason that the thread was closed. Defaults to null when no reason is recorded. + The description of the tool. - - `type: "closed"` + - `type: "mcp_list_tools"` - Status discriminator that is always `closed`. + The type of the item. Always `mcp_list_tools`. - - `"closed"` + - `"mcp_list_tools"` - - `title: string` + - `agent: optional object { agent_name }` - Optional human-readable title for the thread. Defaults to null when no title has been generated. + The agent that produced this item. - - `user: string` + - `agent_name: string` - Free-form string that identifies your end user who owns the thread. + The canonical name of the agent that produced this item. -- `first_id: string` + - `error: optional string` - The ID of the first item in the list. + Error message if the server could not list tools. -- `has_more: boolean` + - `McpApprovalRequest object { id, arguments, name, 3 more }` - Whether there are more items available. + A request for human approval of a tool invocation. -- `last_id: string` + - `id: string` - The ID of the last item in the list. + The unique ID of the approval request. -- `object: "list"` + - `arguments: string` - The type of object returned, must be `list`. + A JSON string of arguments for the tool. - - `"list"` + - `name: string` -### Example + The name of the tool to run. -```http -curl https://api.openai.com/v1/chatkit/threads \ - -H 'OpenAI-Beta: chatkit_beta=v1' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `server_label: string` -#### Response + The label of the MCP server making the request. -```json -{ - "data": [ - { - "id": "cthr_def456", - "created_at": 1712345600, - "object": "chatkit.thread", - "status": { - "type": "active" - }, - "title": "Demo feedback", - "user": "user_456" - } - ], - "first_id": "first_id", - "has_more": true, - "last_id": "last_id", - "object": "list" -} -``` + - `type: "mcp_approval_request"` -### Example + The type of the item. Always `mcp_approval_request`. -```http -curl "https://api.openai.com/v1/chatkit/threads?limit=2&order=desc" \ - -H "OpenAI-Beta: chatkit_beta=v1" \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `"mcp_approval_request"` -#### Response + - `agent: optional object { agent_name }` -```json -{ - "data": [ - { - "id": "cthr_abc123", - "object": "chatkit.thread", - "title": "Customer escalation" - }, - { - "id": "cthr_def456", - "object": "chatkit.thread", - "title": "Demo feedback" - } - ], - "has_more": false, - "object": "list" -} -``` + The agent that produced this item. -## Domain Types + - `agent_name: string` -### Chat Session + The canonical name of the agent that produced this item. -- `ChatSession object { id, chatkit_configuration, client_secret, 7 more }` + - `McpApprovalResponse object { id, approval_request_id, approve, 3 more }` - Represents a ChatKit session and its resolved configuration. + A response to an MCP approval request. - `id: string` - Identifier for the ChatKit session. + The unique ID of the approval response - - `chatkit_configuration: ChatSessionChatKitConfiguration` + - `approval_request_id: string` - Resolved ChatKit feature configuration for the session. + The ID of the approval request being answered. - - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` + - `approve: boolean` - Automatic thread titling preferences. + Whether the request was approved. - - `enabled: boolean` + - `type: "mcp_approval_response"` - Whether automatic thread titling is enabled. + The type of the item. Always `mcp_approval_response`. - - `file_upload: ChatSessionFileUpload` + - `"mcp_approval_response"` - Upload settings for the session. + - `agent: optional object { agent_name }` - - `enabled: boolean` + The agent that produced this item. - Indicates if uploads are enabled for the session. + - `agent_name: string` - - `max_file_size: number` + The canonical name of the agent that produced this item. - Maximum upload size in megabytes. + - `reason: optional string` - - `max_files: number` + Optional reason for the decision. - Maximum number of uploads allowed during the session. + - `McpCall object { id, arguments, name, 7 more }` - - `history: ChatSessionHistory` + An invocation of a tool on an MCP server. - History retention configuration. + - `id: string` - - `enabled: boolean` + The unique ID of the tool call. - Indicates if chat history is persisted for the session. + - `arguments: string` - - `recent_threads: number` + A JSON string of the arguments passed to the tool. - Number of prior threads surfaced in history views. Defaults to null when all history is retained. + - `name: string` - - `client_secret: string` + The name of the tool that was run. - Ephemeral client secret that authenticates session requests. + - `server_label: string` - - `expires_at: number` + The label of the MCP server running the tool. - Unix timestamp (in seconds) for when the session expires. + - `type: "mcp_call"` - - `max_requests_per_1_minute: number` + The type of the item. Always `mcp_call`. - Convenience copy of the per-minute request limit. + - `"mcp_call"` - - `object: "chatkit.session"` + - `agent: optional object { agent_name }` - Type discriminator that is always `chatkit.session`. + The agent that produced this item. - - `"chatkit.session"` + - `agent_name: string` - - `rate_limits: ChatSessionRateLimits` + The canonical name of the agent that produced this item. - Resolved rate limit values. + - `approval_request_id: optional string` - - `max_requests_per_1_minute: number` + 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. - Maximum allowed requests per one-minute window. + - `error: optional string` - - `status: ChatSessionStatus` + The error from the tool call, if any. - Current lifecycle state of the session. + - `output: optional string` - - `"active"` + The output from the tool call. - - `"expired"` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - - `"cancelled"` + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `user: string` + - `"in_progress"` - User identifier associated with the session. + - `"completed"` - - `workflow: ChatKitWorkflow` + - `"incomplete"` - Workflow metadata for the session. + - `"calling"` - - `id: string` + - `"failed"` - Identifier of the workflow backing the session. + - `CustomToolCall object { id, call_id, input, 7 more }` - - `state_variables: map[string or boolean or number]` + - `id: string` - State variable key-value pairs applied when invoking the workflow. Defaults to null when no overrides were provided. + The unique ID of the custom tool call item. - - `string` + - `call_id: string` - - `boolean` + An identifier used to map this custom tool call to a tool call output. - - `number` + - `input: string` - - `tracing: object { enabled }` + The input for the custom tool call generated by the model. - Tracing settings applied to the workflow. + - `name: string` - - `enabled: boolean` + The name of the custom tool being called. - Indicates whether tracing is enabled. + - `status: "in_progress" or "completed" or "incomplete"` - - `version: string` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Specific workflow version used for the session. Defaults to null when using the latest deployment. + - `"in_progress"` -### Chat Session Automatic Thread Titling + - `"completed"` -- `ChatSessionAutomaticThreadTitling object { enabled }` + - `"incomplete"` - Automatic thread title preferences for the session. + - `type: "custom_tool_call"` - - `enabled: boolean` + The type of the custom tool call. Always `custom_tool_call`. - Whether automatic thread titling is enabled. + - `"custom_tool_call"` -### Chat Session ChatKit Configuration + - `agent: optional object { agent_name }` -- `ChatSessionChatKitConfiguration object { automatic_thread_titling, file_upload, history }` + The agent that produced this item. - ChatKit configuration for the session. + - `agent_name: string` - - `automatic_thread_titling: ChatSessionAutomaticThreadTitling` + The canonical name of the agent that produced this item. - Automatic thread titling preferences. + - `caller: optional object { type } or object { caller_id, type }` - - `enabled: boolean` + The execution context that produced this tool call. - Whether automatic thread titling is enabled. + - `Direct object { type }` - - `file_upload: ChatSessionFileUpload` + - `type: "direct"` - Upload settings for the session. + - `"direct"` - - `enabled: boolean` + - `Program object { caller_id, type }` - Indicates if uploads are enabled for the session. + - `caller_id: string` - - `max_file_size: number` + The call ID of the program item that produced this tool call. - Maximum upload size in megabytes. + - `type: "program"` - - `max_files: number` + - `"program"` - Maximum number of uploads allowed during the session. + - `created_by: optional string` - - `history: ChatSessionHistory` + The identifier of the actor that created the item. - History retention configuration. + - `namespace: optional string` - - `enabled: boolean` + The namespace of the custom tool being called. - Indicates if chat history is persisted for the session. + - `CustomToolCallOutput object { id, call_id, output, 5 more }` - - `recent_threads: number` + - `id: string` - Number of prior threads surfaced in history views. Defaults to null when all history is retained. + The unique ID of the custom tool call output item. -### Chat Session ChatKit Configuration Param + - `call_id: string` -- `ChatSessionChatKitConfigurationParam object { automatic_thread_titling, file_upload, history }` + The call ID, used to map this custom tool call output to a custom tool call. - Optional per-session configuration settings for ChatKit behavior. + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `automatic_thread_titling: optional object { enabled }` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - Configuration for automatic thread titling. When omitted, automatic thread titling is enabled by default. + - `StringOutput = string` - - `enabled: optional boolean` + A string of the output of the custom tool call. - Enable automatic thread title generation. Defaults to true. + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `file_upload: optional object { enabled, max_file_size, max_files }` + Text, image, or file output of the custom tool call. - Configuration for upload enablement and limits. When omitted, uploads are disabled by default (max_files 10, max_file_size 512 MB). + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `enabled: optional boolean` + A text input to the model. - Enable uploads for this session. Defaults to false. + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `max_file_size: optional number` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - Maximum size in megabytes for each uploaded file. Defaults to 512 MB, which is the maximum allowable size. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `max_files: optional number` + A file input to the model. - Maximum number of files that can be uploaded to the session. Defaults to 10. + - `status: "in_progress" or "completed" or "incomplete"` - - `history: optional object { enabled, recent_threads }` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Configuration for chat history retention. When omitted, history is enabled by default with no limit on recent_threads (null). + - `"in_progress"` - - `enabled: optional boolean` + - `"completed"` - Enables chat users to access previous ChatKit threads. Defaults to true. + - `"incomplete"` - - `recent_threads: optional number` + - `type: "custom_tool_call_output"` - Number of recent ChatKit threads users have access to. Defaults to unlimited when unset. + The type of the custom tool call output. Always `custom_tool_call_output`. -### Chat Session Expires After Param + - `"custom_tool_call_output"` -- `ChatSessionExpiresAfterParam object { anchor, seconds }` + - `agent: optional object { agent_name }` - Controls when the session expires relative to an anchor timestamp. + The agent that produced this item. - - `anchor: "created_at"` + - `agent_name: string` - Base timestamp used to calculate expiration. Currently fixed to `created_at`. + The canonical name of the agent that produced this item. - - `"created_at"` + - `caller: optional object { type } or object { caller_id, type }` - - `seconds: number` + The execution context that produced this tool call. - Number of seconds after the anchor when the session expires. + - `Direct object { type }` -### Chat Session File Upload + - `type: "direct"` -- `ChatSessionFileUpload object { enabled, max_file_size, max_files }` + The caller type. Always `direct`. - Upload permissions and limits applied to the session. + - `"direct"` - - `enabled: boolean` + - `Program object { caller_id, type }` - Indicates if uploads are enabled for the session. + - `caller_id: string` - - `max_file_size: number` + The call ID of the program item that produced this tool call. - Maximum upload size in megabytes. + - `type: "program"` - - `max_files: number` + The caller type. Always `program`. - Maximum number of uploads allowed during the session. + - `"program"` -### Chat Session History + - `created_by: optional string` -- `ChatSessionHistory object { enabled, recent_threads }` + The identifier of the actor that created the item. - History retention preferences returned for the session. + - `first_id: string` - - `enabled: boolean` + The ID of the first item in the list. - Indicates if chat history is persisted for the session. + - `has_more: boolean` - - `recent_threads: number` + Whether there are more items available. - Number of prior threads surfaced in history views. Defaults to null when all history is retained. + - `last_id: string` -### Chat Session Rate Limits + The ID of the last item in the list. -- `ChatSessionRateLimits object { max_requests_per_1_minute }` + - `object: "list"` - Active per-minute request limit for the session. + The type of object returned, must be `list`. - - `max_requests_per_1_minute: number` + - `"list"` - Maximum allowed requests per one-minute window. +# Input Tokens -### Chat Session Rate Limits Param +## Get input token counts -- `ChatSessionRateLimitsParam object { max_requests_per_1_minute }` +**post** `/responses/input_tokens?beta=true` - Controls request rate limits for the session. +Returns input token counts of the request. - - `max_requests_per_1_minute: optional number` +Returns an object with `object` set to `response.input_tokens` and an `input_tokens` count. - Maximum number of requests allowed per minute for the session. Defaults to 10. +### Header Parameters -### Chat Session Status +- `"openai-beta": optional array of "responses_multi_agent=v1"` -- `ChatSessionStatus = "active" or "expired" or "cancelled"` + - `"responses_multi_agent=v1"` - - `"active"` +### Body Parameters - - `"expired"` +- `conversation: optional string or BetaResponseConversationParam` - - `"cancelled"` + 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. -### Chat Session Workflow Param + - `ConversationID = string` -- `ChatSessionWorkflowParam object { id, state_variables, tracing, version }` + The unique ID of the conversation. - Workflow reference and overrides applied to the chat session. + - `BetaResponseConversationParam object { id }` + + The conversation that this response belongs to. - `id: string` - Identifier for the workflow invoked by the session. + The unique ID of the conversation. - - `state_variables: optional map[string or boolean or number]` +- `input: optional string or array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - State variables forwarded to the workflow. Keys may be up to 64 characters, values must be primitive types, and the map defaults to an empty object. + Text, image, or file inputs to the model, used to generate a response - `string` - - `boolean` - - - `number` + A text input to the model, equivalent to a text input with the `user` role. - - `tracing: optional object { enabled }` + - `array of BetaEasyInputMessage or object { content, role, agent, 2 more } or BetaResponseOutputMessage or 32 more` - Optional tracing overrides for the workflow invocation. When omitted, tracing is enabled by default. + A list of one or many input items to the model, containing different content types. - - `enabled: optional boolean` + - `BetaEasyInputMessage object { content, role, phase, type }` - Whether tracing is enabled during the session. Defaults to true. + 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. - - `version: optional string` + - `content: string or BetaResponseInputMessageContentList` - Specific workflow version to run. Defaults to the latest deployed version. + Text, image, or audio input to the model, used to generate a response. + Can also contain previous assistant responses. -### ChatKit Attachment + - `TextInput = string` -- `ChatKitAttachment object { id, mime_type, name, 2 more }` + A text input to the model. - Attachment metadata included on thread items. + - `BetaResponseInputMessageContentList = array of BetaResponseInputContent` - - `id: string` + A list of one or many input items to the model, containing different content + types. - Identifier for the attachment. + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - - `mime_type: string` + A text input to the model. - MIME type of the attachment. + - `text: string` - - `name: string` + The text input to the model. - Original display name for the attachment. + - `type: "input_text"` - - `preview_url: string` + The type of the input item. Always `input_text`. - Preview URL for rendering the attachment inline. + - `"input_text"` - - `type: "image" or "file"` + - `prompt_cache_breakpoint: optional object { mode }` - Attachment discriminator. + 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. - - `"image"` + - `mode: "explicit"` - - `"file"` + The breakpoint mode. Always `explicit`. -### ChatKit Response Output Text + - `"explicit"` -- `ChatKitResponseOutputText object { annotations, text, type }` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - Assistant response text accompanied by optional annotations. + An image input to the model. Learn about [image inputs](/docs/guides/vision). - - `annotations: array of object { source, type } or object { source, type }` + - `detail: "low" or "high" or "auto" or "original"` - Ordered list of annotations attached to the response text. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `File object { source, type }` + - `"low"` - Annotation that references an uploaded file. + - `"high"` - - `source: object { filename, type }` + - `"auto"` - File attachment referenced by the annotation. + - `"original"` - - `filename: string` + - `type: "input_image"` - Filename referenced by the annotation. + The type of the input item. Always `input_image`. - - `type: "file"` + - `"input_image"` - Type discriminator that is always `file`. + - `file_id: optional string` - - `"file"` + The ID of the file to be sent to the model. - - `type: "file"` + - `image_url: optional string` - Type discriminator that is always `file` for this annotation. + The URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - - `"file"` + - `prompt_cache_breakpoint: optional object { mode }` - - `URL object { source, 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. - Annotation that references a URL. + - `mode: "explicit"` - - `source: object { type, url }` + The breakpoint mode. Always `explicit`. - URL referenced by the annotation. + - `"explicit"` - - `type: "url"` + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - Type discriminator that is always `url`. + A file input to the model. - - `"url"` + - `type: "input_file"` - - `url: string` + The type of the input item. Always `input_file`. - URL referenced by the annotation. + - `"input_file"` - - `type: "url"` + - `detail: optional "auto" or "low" or "high"` - Type discriminator that is always `url` for this annotation. + 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`. - - `"url"` + - `"auto"` - - `text: string` + - `"low"` - Assistant generated text. + - `"high"` - - `type: "output_text"` + - `file_data: optional string` - Type discriminator that is always `output_text`. + The content of the file to be sent to the model. - - `"output_text"` + - `file_id: optional string` -### ChatKit Thread + The ID of the file to be sent to the model. -- `ChatKitThread object { id, created_at, object, 3 more }` + - `file_url: optional string` - Represents a ChatKit thread and its current status. + The URL of the file to be sent to the model. - - `id: string` + - `filename: optional string` - Identifier of the thread. + The name of the file to be sent to the model. - - `created_at: number` + - `prompt_cache_breakpoint: optional object { mode }` - Unix timestamp (in seconds) for when the thread was created. + 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. - - `object: "chatkit.thread"` + - `mode: "explicit"` - Type discriminator that is always `chatkit.thread`. + The breakpoint mode. Always `explicit`. - - `"chatkit.thread"` + - `"explicit"` - - `status: object { type } or object { reason, type } or object { reason, type }` + - `role: "user" or "assistant" or "system" or "developer"` - Current status for the thread. Defaults to `active` for newly created threads. + The role of the message input. One of `user`, `assistant`, `system`, or + `developer`. - - `Active object { type }` + - `"user"` - Indicates that a thread is active. + - `"assistant"` - - `type: "active"` + - `"system"` - Status discriminator that is always `active`. + - `"developer"` - - `"active"` + - `phase: optional "commentary" or "final_answer"` - - `Locked object { reason, type }` + 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. - Indicates that a thread is locked and cannot accept new input. + - `"commentary"` - - `reason: string` + - `"final_answer"` - Reason that the thread was locked. Defaults to null when no reason is recorded. + - `type: optional "message"` - - `type: "locked"` + The type of the message input. Always `message`. - Status discriminator that is always `locked`. + - `"message"` - - `"locked"` + - `Message object { content, role, agent, 2 more }` - - `Closed object { reason, 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. - Indicates that a thread has been closed. + - `content: BetaResponseInputMessageContentList` - - `reason: string` + A list of one or many input items to the model, containing different content + types. - Reason that the thread was closed. Defaults to null when no reason is recorded. + - `role: "user" or "system" or "developer"` - - `type: "closed"` + The role of the message input. One of `user`, `system`, or `developer`. - Status discriminator that is always `closed`. + - `"user"` - - `"closed"` + - `"system"` - - `title: string` + - `"developer"` - Optional human-readable title for the thread. Defaults to null when no title has been generated. + - `agent: optional object { agent_name }` - - `user: string` + The agent that produced this item. - Free-form string that identifies your end user who owns the thread. + - `agent_name: string` -### ChatKit Thread Assistant Message Item + The canonical name of the agent that produced this item. -- `ChatKitThreadAssistantMessageItem object { id, content, created_at, 3 more }` + - `status: optional "in_progress" or "completed" or "incomplete"` - Assistant-authored message within a thread. + The status of item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `id: string` + - `"in_progress"` - Identifier of the thread item. + - `"completed"` - - `content: array of ChatKitResponseOutputText` + - `"incomplete"` - Ordered assistant response segments. + - `type: optional "message"` - - `annotations: array of object { source, type } or object { source, type }` + The type of the message input. Always set to `message`. - Ordered list of annotations attached to the response text. + - `"message"` - - `File object { source, type }` + - `BetaResponseOutputMessage object { id, content, role, 4 more }` - Annotation that references an uploaded file. + An output message from the model. - - `source: object { filename, type }` + - `id: string` - File attachment referenced by the annotation. + The unique ID of the output message. - - `filename: string` + - `content: array of BetaResponseOutputText or BetaResponseOutputRefusal` - Filename referenced by the annotation. + The content of the output message. - - `type: "file"` + - `BetaResponseOutputText object { annotations, logprobs, text, type }` - Type discriminator that is always `file`. + A text output from the model. - - `"file"` + - `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: "file"` + The annotations of the text output. - Type discriminator that is always `file` for this annotation. + - `FileCitation object { file_id, filename, index, type }` - - `"file"` + A citation to a file. - - `URL object { source, type }` + - `file_id: string` - Annotation that references a URL. + The ID of the file. - - `source: object { type, url }` + - `filename: string` - URL referenced by the annotation. + The filename of the file cited. - - `type: "url"` + - `index: number` - Type discriminator that is always `url`. + The index of the file in the list of files. - - `"url"` + - `type: "file_citation"` - - `url: string` + The type of the file citation. Always `file_citation`. - URL referenced by the annotation. + - `"file_citation"` - - `type: "url"` + - `URLCitation object { end_index, start_index, title, 2 more }` - Type discriminator that is always `url` for this annotation. + A citation for a web resource used to generate a model response. - - `"url"` + - `end_index: number` - - `text: string` + The index of the last character of the URL citation in the message. - Assistant generated text. + - `start_index: number` - - `type: "output_text"` + The index of the first character of the URL citation in the message. - Type discriminator that is always `output_text`. + - `title: string` - - `"output_text"` + The title of the web resource. - - `created_at: number` + - `type: "url_citation"` - Unix timestamp (in seconds) for when the item was created. + The type of the URL citation. Always `url_citation`. - - `object: "chatkit.thread_item"` + - `"url_citation"` - Type discriminator that is always `chatkit.thread_item`. + - `url: string` - - `"chatkit.thread_item"` + The URL of the web resource. - - `thread_id: string` + - `ContainerFileCitation object { container_id, end_index, file_id, 3 more }` - Identifier of the parent thread. + A citation for a container file used to generate a model response. - - `type: "chatkit.assistant_message"` + - `container_id: string` - Type discriminator that is always `chatkit.assistant_message`. + The ID of the container file. - - `"chatkit.assistant_message"` + - `end_index: number` -### ChatKit Thread Item List + The index of the last character of the container file citation in the message. -- `ChatKitThreadItemList object { data, first_id, has_more, 2 more }` + - `file_id: string` - A paginated list of thread items rendered for the ChatKit API. + The ID of the file. - - `data: array of ChatKitThreadUserMessageItem or ChatKitThreadAssistantMessageItem or ChatKitWidgetItem or 3 more` + - `filename: string` - A list of items + The filename of the container file cited. - - `ChatKitThreadUserMessageItem object { id, attachments, content, 5 more }` + - `start_index: number` - User-authored messages within a thread. + The index of the first character of the container file citation in the message. - - `id: string` + - `type: "container_file_citation"` - Identifier of the thread item. + The type of the container file citation. Always `container_file_citation`. - - `attachments: array of ChatKitAttachment` + - `"container_file_citation"` - Attachments associated with the user message. Defaults to an empty list. + - `FilePath object { file_id, index, type }` - - `id: string` + A path to a file. - Identifier for the attachment. + - `file_id: string` - - `mime_type: string` + The ID of the file. - MIME type of the attachment. + - `index: number` - - `name: string` + The index of the file in the list of files. - Original display name for the attachment. + - `type: "file_path"` - - `preview_url: string` + The type of the file path. Always `file_path`. - Preview URL for rendering the attachment inline. + - `"file_path"` - - `type: "image" or "file"` + - `logprobs: array of object { token, bytes, logprob, top_logprobs }` - Attachment discriminator. + - `token: string` - - `"image"` + - `bytes: array of number` - - `"file"` + - `logprob: number` - - `content: array of object { text, type } or object { text, type }` + - `top_logprobs: array of object { token, bytes, logprob }` - Ordered content elements supplied by the user. + - `token: string` - - `InputText object { text, type }` + - `bytes: array of number` - Text block that a user contributed to the thread. + - `logprob: number` - `text: string` - Plain-text content supplied by the user. - - - `type: "input_text"` - - Type discriminator that is always `input_text`. - - - `"input_text"` - - - `QuotedText object { text, type }` + The text output from the model. - Quoted snippet that the user referenced in their message. + - `type: "output_text"` - - `text: string` + The type of the output text. Always `output_text`. - Quoted text content. + - `"output_text"` - - `type: "quoted_text"` + - `BetaResponseOutputRefusal object { refusal, type }` - Type discriminator that is always `quoted_text`. + A refusal from the model. - - `"quoted_text"` + - `refusal: string` - - `created_at: number` + The refusal explanation from the model. - Unix timestamp (in seconds) for when the item was created. + - `type: "refusal"` - - `inference_options: object { model, tool_choice }` + The type of the refusal. Always `refusal`. - Inference overrides applied to the message. Defaults to null when unset. + - `"refusal"` - - `model: string` + - `role: "assistant"` - Model name that generated the response. Defaults to null when using the session default. + The role of the output message. Always `assistant`. - - `tool_choice: object { id }` + - `"assistant"` - Preferred tool to invoke. Defaults to null when ChatKit should auto-select. + - `status: "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. - Identifier of the requested tool. + - `"in_progress"` - - `object: "chatkit.thread_item"` + - `"completed"` - Type discriminator that is always `chatkit.thread_item`. + - `"incomplete"` - - `"chatkit.thread_item"` + - `type: "message"` - - `thread_id: string` + The type of the output message. Always `message`. - Identifier of the parent thread. + - `"message"` - - `type: "chatkit.user_message"` + - `agent: optional object { agent_name }` - - `"chatkit.user_message"` + The agent that produced this item. - - `ChatKitThreadAssistantMessageItem object { id, content, created_at, 3 more }` + - `agent_name: string` - Assistant-authored message within a thread. + The canonical name of the agent that produced this item. - - `id: string` + - `phase: optional "commentary" or "final_answer"` - Identifier of the thread item. + 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. - - `content: array of ChatKitResponseOutputText` + - `"commentary"` - Ordered assistant response segments. + - `"final_answer"` - - `annotations: array of object { source, type } or object { source, type }` + - `FileSearchCall object { id, queries, status, 3 more }` - Ordered list of annotations attached to the response text. + The results of a file search tool call. See the + [file search guide](/docs/guides/tools-file-search) for more information. - - `File object { source, type }` + - `id: string` - Annotation that references an uploaded file. + The unique ID of the file search tool call. - - `source: object { filename, type }` + - `queries: array of string` - File attachment referenced by the annotation. + The queries used to search for files. - - `filename: string` + - `status: "in_progress" or "searching" or "completed" or 2 more` - Filename referenced by the annotation. + The status of the file search tool call. One of `in_progress`, + `searching`, `incomplete` or `failed`, - - `type: "file"` + - `"in_progress"` - Type discriminator that is always `file`. + - `"searching"` - - `"file"` + - `"completed"` - - `type: "file"` + - `"incomplete"` - Type discriminator that is always `file` for this annotation. + - `"failed"` - - `"file"` + - `type: "file_search_call"` - - `URL object { source, type }` + The type of the file search tool call. Always `file_search_call`. - Annotation that references a URL. + - `"file_search_call"` - - `source: object { type, url }` + - `agent: optional object { agent_name }` - URL referenced by the annotation. + The agent that produced this item. - - `type: "url"` + - `agent_name: string` - Type discriminator that is always `url`. + The canonical name of the agent that produced this item. - - `"url"` + - `results: optional array of object { attributes, file_id, filename, 2 more }` - - `url: string` + The results of the file search tool call. - URL referenced by the annotation. + - `attributes: optional map[string or number or boolean]` - - `type: "url"` + 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. - Type discriminator that is always `url` for this annotation. + - `string` - - `"url"` + - `number` - - `text: string` + - `boolean` - Assistant generated text. + - `file_id: optional string` - - `type: "output_text"` + The unique ID of the file. - Type discriminator that is always `output_text`. + - `filename: optional string` - - `"output_text"` + The name of the file. - - `created_at: number` + - `score: optional number` - Unix timestamp (in seconds) for when the item was created. + The relevance score of the file - a value between 0 and 1. - - `object: "chatkit.thread_item"` + - `text: optional string` - Type discriminator that is always `chatkit.thread_item`. + The text that was retrieved from the file. - - `"chatkit.thread_item"` + - `ComputerCall object { id, call_id, pending_safety_checks, 5 more }` - - `thread_id: string` + A tool call to a computer use tool. See the + [computer use guide](/docs/guides/tools-computer-use) for more information. - Identifier of the parent thread. + - `id: string` - - `type: "chatkit.assistant_message"` + The unique ID of the computer call. - Type discriminator that is always `chatkit.assistant_message`. + - `call_id: string` - - `"chatkit.assistant_message"` + An identifier used when responding to the tool call with output. - - `ChatKitWidgetItem object { id, created_at, object, 3 more }` + - `pending_safety_checks: array of object { id, code, message }` - Thread item that renders a widget payload. + The pending safety checks for the computer call. - `id: string` - Identifier of the thread item. - - - `created_at: number` - - Unix timestamp (in seconds) for when the item was created. + The ID of the pending safety check. - - `object: "chatkit.thread_item"` + - `code: optional string` - Type discriminator that is always `chatkit.thread_item`. + The type of the pending safety check. - - `"chatkit.thread_item"` + - `message: optional string` - - `thread_id: string` + Details about the pending safety check. - Identifier of the parent thread. + - `status: "in_progress" or "completed" or "incomplete"` - - `type: "chatkit.widget"` + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - Type discriminator that is always `chatkit.widget`. + - `"in_progress"` - - `"chatkit.widget"` + - `"completed"` - - `widget: string` + - `"incomplete"` - Serialized widget payload rendered in the UI. + - `type: "computer_call"` - - `ChatKitClientToolCall object { id, arguments, call_id, 7 more }` + The type of the computer call. Always `computer_call`. - Record of a client side tool invocation initiated by the assistant. + - `"computer_call"` - - `id: string` + - `action: optional BetaComputerAction` - Identifier of the thread item. + A click action. - - `arguments: string` + - `Click object { button, type, x, 2 more }` - JSON-encoded arguments that were sent to the tool. + A click action. - - `call_id: string` + - `button: "left" or "right" or "wheel" or 2 more` - Identifier for the client tool call. + Indicates which mouse button was pressed during the click. One of `left`, `right`, `wheel`, `back`, or `forward`. - - `created_at: number` + - `"left"` - Unix timestamp (in seconds) for when the item was created. + - `"right"` - - `name: string` + - `"wheel"` - Tool name that was invoked. + - `"back"` - - `object: "chatkit.thread_item"` + - `"forward"` - Type discriminator that is always `chatkit.thread_item`. + - `type: "click"` - - `"chatkit.thread_item"` + Specifies the event type. For a click action, this property is always `click`. - - `output: string` + - `"click"` - JSON-encoded output captured from the tool. Defaults to null while execution is in progress. + - `x: number` - - `status: "in_progress" or "completed"` + The x-coordinate where the click occurred. - Execution status for the tool call. + - `y: number` - - `"in_progress"` + The y-coordinate where the click occurred. - - `"completed"` + - `keys: optional array of string` - - `thread_id: string` + The keys being held while clicking. - Identifier of the parent thread. + - `DoubleClick object { keys, type, x, y }` - - `type: "chatkit.client_tool_call"` + A double click action. - Type discriminator that is always `chatkit.client_tool_call`. + - `keys: array of string` - - `"chatkit.client_tool_call"` + The keys being held while double-clicking. - - `ChatKitTask object { id, created_at, heading, 5 more }` + - `type: "double_click"` - Task emitted by the workflow to show progress and status updates. + Specifies the event type. For a double click action, this property is always set to `double_click`. - - `id: string` + - `"double_click"` - Identifier of the thread item. + - `x: number` - - `created_at: number` + The x-coordinate where the double click occurred. - Unix timestamp (in seconds) for when the item was created. + - `y: number` - - `heading: string` + The y-coordinate where the double click occurred. - Optional heading for the task. Defaults to null when not provided. + - `Drag object { path, type, keys }` - - `object: "chatkit.thread_item"` + A drag action. - Type discriminator that is always `chatkit.thread_item`. + - `path: array of object { x, y }` - - `"chatkit.thread_item"` + An array of coordinates representing the path of the drag action. Coordinates will appear as an array of objects, eg - - `summary: string` + ``` + [ + { x: 100, y: 200 }, + { x: 200, y: 300 } + ] + ``` - Optional summary that describes the task. Defaults to null when omitted. + - `x: number` - - `task_type: "custom" or "thought"` + The x-coordinate. - Subtype for the task. + - `y: number` - - `"custom"` + The y-coordinate. - - `"thought"` + - `type: "drag"` - - `thread_id: string` + Specifies the event type. For a drag action, this property is always set to `drag`. - Identifier of the parent thread. + - `"drag"` - - `type: "chatkit.task"` + - `keys: optional array of string` - Type discriminator that is always `chatkit.task`. + The keys being held while dragging the mouse. - - `"chatkit.task"` + - `Keypress object { keys, type }` - - `ChatKitTaskGroup object { id, created_at, object, 3 more }` + A collection of keypresses the model would like to perform. - Collection of workflow tasks grouped together in the thread. + - `keys: array of string` - - `id: string` + The combination of keys the model is requesting to be pressed. This is an array of strings, each representing a key. - Identifier of the thread item. + - `type: "keypress"` - - `created_at: number` + Specifies the event type. For a keypress action, this property is always set to `keypress`. - Unix timestamp (in seconds) for when the item was created. + - `"keypress"` - - `object: "chatkit.thread_item"` + - `Move object { type, x, y, keys }` - Type discriminator that is always `chatkit.thread_item`. + A mouse move action. - - `"chatkit.thread_item"` + - `type: "move"` - - `tasks: array of object { heading, summary, type }` + Specifies the event type. For a move action, this property is always set to `move`. - Tasks included in the group. + - `"move"` - - `heading: string` + - `x: number` - Optional heading for the grouped task. Defaults to null when not provided. + The x-coordinate to move to. - - `summary: string` + - `y: number` - Optional summary that describes the grouped task. Defaults to null when omitted. + The y-coordinate to move to. - - `type: "custom" or "thought"` + - `keys: optional array of string` - Subtype for the grouped task. + The keys being held while moving the mouse. - - `"custom"` + - `Screenshot object { type }` - - `"thought"` + A screenshot action. - - `thread_id: string` + - `type: "screenshot"` - Identifier of the parent thread. + Specifies the event type. For a screenshot action, this property is always set to `screenshot`. - - `type: "chatkit.task_group"` + - `"screenshot"` - Type discriminator that is always `chatkit.task_group`. + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - - `"chatkit.task_group"` + A scroll action. - - `first_id: string` + - `scroll_x: number` - The ID of the first item in the list. + The horizontal scroll distance. - - `has_more: boolean` + - `scroll_y: number` - Whether there are more items available. + The vertical scroll distance. - - `last_id: string` + - `type: "scroll"` - The ID of the last item in the list. + Specifies the event type. For a scroll action, this property is always set to `scroll`. - - `object: "list"` + - `"scroll"` - The type of object returned, must be `list`. + - `x: number` - - `"list"` + The x-coordinate where the scroll occurred. -### ChatKit Thread User Message Item + - `y: number` -- `ChatKitThreadUserMessageItem object { id, attachments, content, 5 more }` + The y-coordinate where the scroll occurred. - User-authored messages within a thread. + - `keys: optional array of string` - - `id: string` + The keys being held while scrolling. - Identifier of the thread item. + - `Type object { text, type }` - - `attachments: array of ChatKitAttachment` + An action to type in text. - Attachments associated with the user message. Defaults to an empty list. + - `text: string` - - `id: string` + The text to type. - Identifier for the attachment. + - `type: "type"` - - `mime_type: string` + Specifies the event type. For a type action, this property is always set to `type`. - MIME type of the attachment. + - `"type"` - - `name: string` + - `Wait object { type }` - Original display name for the attachment. + A wait action. - - `preview_url: string` + - `type: "wait"` - Preview URL for rendering the attachment inline. + Specifies the event type. For a wait action, this property is always set to `wait`. - - `type: "image" or "file"` + - `"wait"` - Attachment discriminator. + - `actions: optional BetaComputerActionList` - - `"image"` + Flattened batched actions for `computer_use`. Each action includes an + `type` discriminator and action-specific fields. - - `"file"` + - `Click object { button, type, x, 2 more }` - - `content: array of object { text, type } or object { text, type }` + A click action. - Ordered content elements supplied by the user. + - `DoubleClick object { keys, type, x, y }` - - `InputText object { text, type }` + A double click action. - Text block that a user contributed to the thread. + - `Drag object { path, type, keys }` - - `text: string` + A drag action. - Plain-text content supplied by the user. + - `Keypress object { keys, type }` - - `type: "input_text"` + A collection of keypresses the model would like to perform. - Type discriminator that is always `input_text`. + - `Move object { type, x, y, keys }` - - `"input_text"` + A mouse move action. - - `QuotedText object { text, type }` + - `Screenshot object { type }` - Quoted snippet that the user referenced in their message. + A screenshot action. - - `text: string` + - `Scroll object { scroll_x, scroll_y, type, 3 more }` - Quoted text content. + A scroll action. - - `type: "quoted_text"` + - `Type object { text, type }` - Type discriminator that is always `quoted_text`. + An action to type in text. - - `"quoted_text"` + - `Wait object { type }` - - `created_at: number` + A wait action. - Unix timestamp (in seconds) for when the item was created. + - `agent: optional object { agent_name }` - - `inference_options: object { model, tool_choice }` + The agent that produced this item. - Inference overrides applied to the message. Defaults to null when unset. + - `agent_name: string` - - `model: string` + The canonical name of the agent that produced this item. - Model name that generated the response. Defaults to null when using the session default. + - `ComputerCallOutput object { call_id, output, type, 4 more }` - - `tool_choice: object { id }` + The output of a computer tool call. - Preferred tool to invoke. Defaults to null when ChatKit should auto-select. + - `call_id: string` - - `id: string` + The ID of the computer tool call that produced the output. - Identifier of the requested tool. + - `output: BetaResponseComputerToolCallOutputScreenshot` - - `object: "chatkit.thread_item"` + A computer screenshot image used with the computer use tool. - Type discriminator that is always `chatkit.thread_item`. + - `type: "computer_screenshot"` - - `"chatkit.thread_item"` + Specifies the event type. For a computer screenshot, this property is + always set to `computer_screenshot`. - - `thread_id: string` + - `"computer_screenshot"` - Identifier of the parent thread. + - `file_id: optional string` - - `type: "chatkit.user_message"` + The identifier of an uploaded file that contains the screenshot. - - `"chatkit.user_message"` + - `image_url: optional string` -### ChatKit Widget Item + The URL of the screenshot image. -- `ChatKitWidgetItem object { id, created_at, object, 3 more }` + - `type: "computer_call_output"` - Thread item that renders a widget payload. + The type of the computer tool call output. Always `computer_call_output`. - - `id: string` + - `"computer_call_output"` - Identifier of the thread item. + - `id: optional string` - - `created_at: number` + The ID of the computer tool call output. - Unix timestamp (in seconds) for when the item was created. + - `acknowledged_safety_checks: optional array of object { id, code, message }` - - `object: "chatkit.thread_item"` + The safety checks reported by the API that have been acknowledged by the developer. - Type discriminator that is always `chatkit.thread_item`. + - `id: string` - - `"chatkit.thread_item"` + The ID of the pending safety check. - - `thread_id: string` + - `code: optional string` - Identifier of the parent thread. + The type of the pending safety check. - - `type: "chatkit.widget"` + - `message: optional string` - Type discriminator that is always `chatkit.widget`. + Details about the pending safety check. - - `"chatkit.widget"` + - `agent: optional object { agent_name }` - - `widget: string` + The agent that produced this item. - Serialized widget payload rendered in the UI. + - `agent_name: string` -### Thread Delete Response + The canonical name of the agent that produced this item. -- `ThreadDeleteResponse object { id, deleted, object }` + - `status: optional "in_progress" or "completed" or "incomplete"` - Confirmation payload returned after deleting a thread. + The status of the message input. One of `in_progress`, `completed`, or `incomplete`. Populated when input items are returned via API. - - `id: string` + - `"in_progress"` - Identifier of the deleted thread. + - `"completed"` - - `deleted: boolean` + - `"incomplete"` - Indicates that the thread has been deleted. + - `WebSearchCall object { id, action, status, 2 more }` - - `object: "chatkit.thread.deleted"` + The results of a web search tool call. See the + [web search guide](/docs/guides/tools-web-search) for more information. - Type discriminator that is always `chatkit.thread.deleted`. + - `id: string` - - `"chatkit.thread.deleted"` + The unique ID of the web search tool call. -# Assistants + - `action: object { type, queries, query, sources } or object { type, url } or object { pattern, type, url }` -## List assistants + 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). -**get** `/assistants` + - `Search object { type, queries, query, sources }` -Returns a list of assistants. + Action type "search" - Performs a web search query. -### Query Parameters + - `type: "search"` -- `after: optional string` + The action type. - A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. + - `"search"` -- `before: optional string` + - `queries: optional array of string` - A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. + The search queries. -- `limit: optional number` + - `query: optional string` - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + The search query. -- `order: optional "asc" or "desc"` + - `sources: optional array of object { type, url }` - Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. + The sources used in the search. - - `"asc"` + - `type: "url"` - - `"desc"` + The type of source. Always `url`. -### Returns + - `"url"` -- `data: array of Assistant` + - `url: string` - - `id: string` + The URL of the source. - The identifier, which can be referenced in API endpoints. + - `OpenPage object { type, url }` - - `created_at: number` + Action type "open_page" - Opens a specific URL from search results. - The Unix timestamp (in seconds) for when the assistant was created. + - `type: "open_page"` - - `description: string` + The action type. - The description of the assistant. The maximum length is 512 characters. + - `"open_page"` - - `instructions: string` + - `url: optional string` - The system instructions that the assistant uses. The maximum length is 256,000 characters. + The URL opened by the model. - - `metadata: Metadata` + - `FindInPage object { pattern, type, url }` - 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. + Action type "find_in_page": Searches for a pattern within a loaded page. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `pattern: string` - - `model: string` + The pattern or text to search for within the page. - ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](/docs/models) for descriptions of them. + - `type: "find_in_page"` - - `name: string` + The action type. - The name of the assistant. The maximum length is 256 characters. + - `"find_in_page"` - - `object: "assistant"` + - `url: string` - The object type, which is always `assistant`. + The URL of the page searched for the pattern. - - `"assistant"` + - `status: "in_progress" or "searching" or "completed" or "failed"` - - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` + The status of the web search tool call. - A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. + - `"in_progress"` - - `CodeInterpreterTool object { type }` + - `"searching"` - - `type: "code_interpreter"` + - `"completed"` - The type of tool being defined: `code_interpreter` + - `"failed"` - - `"code_interpreter"` + - `type: "web_search_call"` - - `FileSearchTool object { type, file_search }` + The type of the web search tool call. Always `web_search_call`. - - `type: "file_search"` + - `"web_search_call"` - The type of tool being defined: `file_search` + - `agent: optional object { agent_name }` - - `"file_search"` + The agent that produced this item. - - `file_search: optional object { max_num_results, ranking_options }` + - `agent_name: string` - Overrides for the file search tool. + The canonical name of the agent that produced this item. - - `max_num_results: optional number` + - `FunctionCall object { arguments, call_id, name, 6 more }` - The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + A tool call to run a function. See the + [function calling guide](/docs/guides/function-calling) for more information. - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `arguments: string` - - `ranking_options: optional object { score_threshold, ranker }` + A JSON string of the arguments to pass to the function. - The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + - `call_id: string` - See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + The unique ID of the function tool call generated by the model. - - `score_threshold: number` + - `name: string` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + The name of the function to run. - - `ranker: optional "auto" or "default_2024_08_21"` + - `type: "function_call"` - The ranker to use for the file search. If not specified will use the `auto` ranker. + The type of the function tool call. Always `function_call`. - - `"auto"` + - `"function_call"` - - `"default_2024_08_21"` + - `id: optional string` - - `FunctionTool object { function, type }` + The unique ID of the function tool call. - - `function: FunctionDefinition` + - `agent: optional object { agent_name }` - - `name: string` + The agent that produced this item. - The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + - `agent_name: string` - - `description: optional string` + The canonical name of the agent that produced this item. - A description of what the function does, used by the model to choose when and how to call the function. + - `caller: optional object { type } or object { caller_id, type }` - - `parameters: optional FunctionParameters` + The execution context that produced this tool call. - The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + - `Direct object { type }` - Omitting `parameters` defines a function with an empty parameter list. + - `type: "direct"` - - `strict: optional boolean` + - `"direct"` - Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-calling). + - `Program object { caller_id, type }` - - `type: "function"` + - `caller_id: string` - The type of tool being defined: `function` + The call ID of the program item that produced this tool call. - - `"function"` + - `type: "program"` - - `response_format: optional AssistantResponseFormatOption` + - `"program"` - Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `namespace: optional string` - Setting to `{ "type": "json_schema", "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 namespace of the function to run. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `status: optional "in_progress" or "completed" or "incomplete"` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"auto"` + - `"in_progress"` - `auto` is the default value + - `"completed"` - - `"auto"` + - `"incomplete"` - - `ResponseFormatText object { type }` + - `FunctionCallOutput object { call_id, output, type, 4 more }` - Default response format. Used to generate text responses. + The output of a function tool call. - - `type: "text"` + - `call_id: string` - The type of response format being defined. Always `text`. + The unique ID of the function tool call generated by the model. - - `"text"` + - `output: string or array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - - `ResponseFormatJSONObject object { type }` + Text, image, or file output of the function tool call. - 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. + - `string` - - `type: "json_object"` + A JSON string of the output of the function tool call. - The type of response format being defined. Always `json_object`. + - `array of BetaResponseInputTextContent or BetaResponseInputImageContent or BetaResponseInputFileContent` - - `"json_object"` + An array of content outputs (text, image, file) for the function tool call. - - `ResponseFormatJSONSchema object { json_schema, type }` + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + A text input to the model. - - `json_schema: object { name, description, schema, strict }` + - `text: string` - Structured Outputs configuration options, including a JSON Schema. + The text input to the model. - - `name: string` + - `type: "input_text"` - 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 type of the input item. Always `input_text`. - - `description: optional string` + - `"input_text"` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `prompt_cache_breakpoint: optional object { mode }` - - `schema: optional map[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. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `mode: "explicit"` - - `strict: optional boolean` + The breakpoint mode. Always `explicit`. - 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). + - `"explicit"` - - `type: "json_schema"` + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - The type of response format being defined. Always `json_schema`. + An image input to the model. Learn about [image inputs](/docs/guides/vision) - - `"json_schema"` + - `type: "input_image"` - - `temperature: optional number` + The type of the input item. Always `input_image`. - 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. + - `"input_image"` - - `tool_resources: optional object { code_interpreter, file_search }` + - `detail: optional "low" or "high" or "auto" or "original"` - A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + The detail level of the image to be sent to the model. One of `high`, `low`, `auto`, or `original`. Defaults to `auto`. - - `code_interpreter: optional object { file_ids }` + - `"low"` - - `file_ids: optional array of string` + - `"high"` - A list of [file](/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. + - `"auto"` - - `file_search: optional object { vector_store_ids }` + - `"original"` - - `vector_store_ids: optional array of string` + - `file_id: optional string` - The ID of the [vector store](/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. + The ID of the file to be sent to the model. - - `top_p: optional number` + - `image_url: optional string` - 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 URL of the image to be sent to the model. A fully qualified URL or base64 encoded image in a data URL. - We generally recommend altering this or temperature but not both. + - `prompt_cache_breakpoint: optional object { mode }` -- `first_id: 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. -- `has_more: boolean` + - `mode: "explicit"` -- `last_id: string` + The breakpoint mode. Always `explicit`. -- `object: string` + - `"explicit"` -### Example + - `BetaResponseInputFileContent object { type, detail, file_data, 4 more }` -```http -curl https://api.openai.com/v1/assistants \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + A file input to the model. -#### Response + - `type: "input_file"` -```json -{ - "data": [ - { - "id": "id", - "created_at": 0, - "description": "description", - "instructions": "instructions", - "metadata": { - "foo": "string" - }, - "model": "model", - "name": "name", - "object": "assistant", - "tools": [ - { - "type": "code_interpreter" - } - ], - "response_format": "auto", - "temperature": 1, - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - }, - "top_p": 1 - } - ], - "first_id": "asst_abc123", - "has_more": false, - "last_id": "asst_abc456", - "object": "list" -} -``` + The type of the input item. Always `input_file`. -### Example + - `"input_file"` -```http -curl "https://api.openai.com/v1/assistants?order=desc&limit=20" \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: assistants=v2" -``` + - `detail: optional "auto" or "low" or "high"` -#### Response + 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`. -```json -{ - "object": "list", - "data": [ - { - "id": "asst_abc123", - "object": "assistant", - "created_at": 1698982736, - "name": "Coding Tutor", - "description": null, - "model": "gpt-4o", - "instructions": "You are a helpful assistant designed to make me better at coding!", - "tools": [], - "tool_resources": {}, - "metadata": {}, - "top_p": 1.0, - "temperature": 1.0, - "response_format": "auto" - }, - { - "id": "asst_abc456", - "object": "assistant", - "created_at": 1698982718, - "name": "My Assistant", - "description": null, - "model": "gpt-4o", - "instructions": "You are a helpful assistant designed to make me better at coding!", - "tools": [], - "tool_resources": {}, - "metadata": {}, - "top_p": 1.0, - "temperature": 1.0, - "response_format": "auto" - }, - { - "id": "asst_abc789", - "object": "assistant", - "created_at": 1698982643, - "name": null, - "description": null, - "model": "gpt-4o", - "instructions": null, - "tools": [], - "tool_resources": {}, - "metadata": {}, - "top_p": 1.0, - "temperature": 1.0, - "response_format": "auto" - } - ], - "first_id": "asst_abc123", - "last_id": "asst_abc789", - "has_more": false -} -``` + - `"auto"` -## Create assistant + - `"low"` -**post** `/assistants` + - `"high"` -Create an assistant with a model and instructions. + - `file_data: optional string` -### Body Parameters + The base64-encoded data of the file to be sent to the model. -- `model: string or "gpt-5" or "gpt-5-mini" or "gpt-5-nano" or 39 more` + - `file_id: optional string` - ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](/docs/models) for descriptions of them. + The ID of the file to be sent to the model. - - `string` + - `file_url: optional string` - - `AssistantSupportedModels = "gpt-5" or "gpt-5-mini" or "gpt-5-nano" or 39 more` + The URL of the file to be sent to the model. - ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](/docs/models) for descriptions of them. + - `filename: optional string` - - `"gpt-5"` + The name of the file to be sent to the model. - - `"gpt-5-mini"` + - `prompt_cache_breakpoint: optional object { mode }` - - `"gpt-5-nano"` + 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. - - `"gpt-5-2025-08-07"` + - `mode: "explicit"` - - `"gpt-5-mini-2025-08-07"` + The breakpoint mode. Always `explicit`. - - `"gpt-5-nano-2025-08-07"` + - `"explicit"` - - `"gpt-4.1"` + - `type: "function_call_output"` - - `"gpt-4.1-mini"` + The type of the function tool call output. Always `function_call_output`. - - `"gpt-4.1-nano"` + - `"function_call_output"` - - `"gpt-4.1-2025-04-14"` + - `id: optional string` - - `"gpt-4.1-mini-2025-04-14"` + The unique ID of the function tool call output. Populated when this item is returned via API. - - `"gpt-4.1-nano-2025-04-14"` + - `agent: optional object { agent_name }` - - `"o3-mini"` + The agent that produced this item. - - `"o3-mini-2025-01-31"` + - `agent_name: string` - - `"o1"` + The canonical name of the agent that produced this item. - - `"o1-2024-12-17"` + - `caller: optional object { type } or object { caller_id, type }` - - `"gpt-4o"` + The execution context that produced this tool call. - - `"gpt-4o-2024-11-20"` + - `Direct object { type }` - - `"gpt-4o-2024-08-06"` + - `type: "direct"` - - `"gpt-4o-2024-05-13"` + The caller type. Always `direct`. - - `"gpt-4o-mini"` + - `"direct"` - - `"gpt-4o-mini-2024-07-18"` + - `Program object { caller_id, type }` - - `"gpt-4.5-preview"` + - `caller_id: string` - - `"gpt-4.5-preview-2025-02-27"` + The call ID of the program item that produced this tool call. - - `"gpt-4-turbo"` + - `type: "program"` - - `"gpt-4-turbo-2024-04-09"` + The caller type. Always `program`. - - `"gpt-4-0125-preview"` + - `"program"` - - `"gpt-4-turbo-preview"` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"gpt-4-1106-preview"` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. Populated when items are returned via API. - - `"gpt-4-vision-preview"` + - `"in_progress"` - - `"gpt-4"` + - `"completed"` - - `"gpt-4-0314"` + - `"incomplete"` - - `"gpt-4-0613"` + - `AgentMessage object { author, content, recipient, 3 more }` - - `"gpt-4-32k"` + A message routed between agents. - - `"gpt-4-32k-0314"` + - `author: string` - - `"gpt-4-32k-0613"` + The sending agent identity. - - `"gpt-3.5-turbo"` + - `content: array of BetaResponseInputTextContent or BetaResponseInputImageContent or object { encrypted_content, type }` - - `"gpt-3.5-turbo-16k"` + Plaintext, image, or encrypted content sent between agents. - - `"gpt-3.5-turbo-0613"` + - `BetaResponseInputTextContent object { text, type, prompt_cache_breakpoint }` - - `"gpt-3.5-turbo-1106"` + A text input to the model. - - `"gpt-3.5-turbo-0125"` + - `BetaResponseInputImageContent object { type, detail, file_id, 2 more }` - - `"gpt-3.5-turbo-16k-0613"` + An image input to the model. Learn about [image inputs](/docs/guides/vision) -- `description: optional string` + - `EncryptedContent object { encrypted_content, type }` - The description of the assistant. The maximum length is 512 characters. + Opaque encrypted content that Responses API decrypts inside trusted model execution. -- `instructions: optional string` + - `encrypted_content: string` - The system instructions that the assistant uses. The maximum length is 256,000 characters. + Opaque encrypted content. -- `metadata: optional Metadata` + - `type: "encrypted_content"` - 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 type of the input item. Always `encrypted_content`. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"encrypted_content"` -- `name: optional string` + - `recipient: string` - The name of the assistant. The maximum length is 256 characters. + The destination agent identity. -- `reasoning_effort: optional ReasoningEffort` + - `type: "agent_message"` - 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 item type. Always `agent_message`. - - `"none"` + - `"agent_message"` - - `"minimal"` + - `id: optional string` - - `"low"` + The unique ID of this agent message item. - - `"medium"` + - `agent: optional object { agent_name }` - - `"high"` + The agent that produced this item. - - `"xhigh"` + - `agent_name: string` - - `"max"` + The canonical name of the agent that produced this item. -- `response_format: optional AssistantResponseFormatOption` + - `MultiAgentCall object { action, arguments, call_id, 3 more }` - Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - Setting to `{ "type": "json_schema", "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 multi-agent action that was executed. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `"spawn_agent"` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `"interrupt_agent"` - - `"auto"` + - `"list_agents"` - `auto` is the default value + - `"send_message"` - - `"auto"` + - `"followup_task"` - - `ResponseFormatText object { type }` + - `"wait_agent"` - Default response format. Used to generate text responses. + - `arguments: string` - - `type: "text"` + The action arguments as a JSON string. - The type of response format being defined. Always `text`. + - `call_id: string` - - `"text"` + The unique ID linking this call to its output. - - `ResponseFormatJSONObject object { type }` + - `type: "multi_agent_call"` - 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 item type. Always `multi_agent_call`. - - `type: "json_object"` + - `"multi_agent_call"` - The type of response format being defined. Always `json_object`. + - `id: optional string` - - `"json_object"` + The unique ID of this multi-agent call. - - `ResponseFormatJSONSchema object { json_schema, type }` + - `agent: optional object { agent_name }` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + The agent that produced this item. - - `json_schema: object { name, description, schema, strict }` + - `agent_name: string` - Structured Outputs configuration options, including a JSON Schema. + The canonical name of the agent that produced this item. - - `name: string` + - `MultiAgentCallOutput object { action, call_id, output, 3 more }` - 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. + - `action: "spawn_agent" or "interrupt_agent" or "list_agents" or 3 more` - - `description: optional string` + The multi-agent action that produced this result. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `"spawn_agent"` - - `schema: optional map[unknown]` + - `"interrupt_agent"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `"list_agents"` - - `strict: optional boolean` + - `"send_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). + - `"followup_task"` - - `type: "json_schema"` + - `"wait_agent"` - The type of response format being defined. Always `json_schema`. + - `call_id: string` - - `"json_schema"` + The unique ID of the multi-agent call. -- `temperature: optional number` + - `output: array of object { text, type, annotations }` - 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. + Text output returned by the multi-agent action. -- `tool_resources: optional object { code_interpreter, file_search }` + - `text: string` - A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + The text content. - - `code_interpreter: optional object { file_ids }` + - `type: "output_text"` - - `file_ids: optional array of string` + The content type. Always `output_text`. - A list of [file](/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. + - `"output_text"` - - `file_search: optional object { vector_store_ids, vector_stores }` + - `annotations: optional 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 }` - - `vector_store_ids: optional array of string` + Citations associated with the text content. - The [vector store](/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. + - `FileCitation object { file_id, filename, index, type }` - - `vector_stores: optional array of object { chunking_strategy, file_ids, metadata }` + - `file_id: string` - A helper to create a [vector store](/docs/api-reference/vector-stores/object) with file_ids and attach it to this assistant. There can be a maximum of 1 vector store attached to the assistant. + The ID of the file. - - `chunking_strategy: optional object { type } or object { static, type }` + - `filename: string` - The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. + The filename of the file cited. - - `AutoChunkingStrategy object { type }` + - `index: number` - The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`. + The index of the file in the list of files. - - `type: "auto"` + - `type: "file_citation"` - Always `auto`. + The citation type. Always `file_citation`. - - `"auto"` + - `"file_citation"` - - `StaticChunkingStrategy object { static, type }` + - `URLCitation object { end_index, start_index, title, 2 more }` - - `static: object { chunk_overlap_tokens, max_chunk_size_tokens }` + - `end_index: number` - - `chunk_overlap_tokens: number` + The index of the last character of the citation in the message. - The number of tokens that overlap between chunks. The default value is `400`. + - `start_index: number` - Note that the overlap must not exceed half of `max_chunk_size_tokens`. + The index of the first character of the citation in the message. - - `max_chunk_size_tokens: number` + - `title: string` - The maximum number of tokens in each chunk. The default value is `800`. The minimum value is `100` and the maximum value is `4096`. + The title of the cited resource. - - `type: "static"` + - `type: "url_citation"` - Always `static`. + The citation type. Always `url_citation`. - - `"static"` + - `"url_citation"` - - `file_ids: optional array of string` + - `url: string` - A list of [file](/docs/api-reference/files) IDs to add to the vector store. For vector stores created before Nov 2025, there can be a maximum of 10,000 files in a vector store. For vector stores created starting in Nov 2025, the limit is 100,000,000 files. + The URL of the cited resource. - - `metadata: optional Metadata` + - `ContainerFileCitation object { container_id, end_index, file_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. + - `container_id: string` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The ID of the container. -- `tools: optional array of CodeInterpreterTool or FileSearchTool or FunctionTool` + - `end_index: number` - A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. + The index of the last character of the citation in the message. - - `CodeInterpreterTool object { type }` + - `file_id: string` - - `type: "code_interpreter"` + The ID of the container file. - The type of tool being defined: `code_interpreter` + - `filename: string` - - `"code_interpreter"` + The filename of the container file cited. - - `FileSearchTool object { type, file_search }` + - `start_index: number` - - `type: "file_search"` + The index of the first character of the citation in the message. - The type of tool being defined: `file_search` + - `type: "container_file_citation"` - - `"file_search"` + The citation type. Always `container_file_citation`. - - `file_search: optional object { max_num_results, ranking_options }` + - `"container_file_citation"` - Overrides for the file search tool. + - `type: "multi_agent_call_output"` - - `max_num_results: optional number` + The item type. Always `multi_agent_call_output`. - The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + - `"multi_agent_call_output"` - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `id: optional string` - - `ranking_options: optional object { score_threshold, ranker }` + The unique ID of this multi-agent call output. - The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + - `agent: optional object { agent_name }` - See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + The agent that produced this item. - - `score_threshold: number` + - `agent_name: string` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + The canonical name of the agent that produced this item. - - `ranker: optional "auto" or "default_2024_08_21"` + - `ToolSearchCall object { arguments, type, id, 4 more }` - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `arguments: unknown` - - `"auto"` + The arguments supplied to the tool search call. - - `"default_2024_08_21"` + - `type: "tool_search_call"` - - `FunctionTool object { function, type }` + The item type. Always `tool_search_call`. - - `function: FunctionDefinition` + - `"tool_search_call"` - - `name: string` + - `id: optional string` - The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + The unique ID of this tool search call. - - `description: optional string` + - `agent: optional object { agent_name }` - A description of what the function does, used by the model to choose when and how to call the function. + The agent that produced this item. - - `parameters: optional FunctionParameters` + - `agent_name: string` - The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + The canonical name of the agent that produced this item. - Omitting `parameters` defines a function with an empty parameter list. + - `call_id: optional string` - - `strict: optional boolean` + The unique ID of the tool search call generated by the model. - Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-calling). + - `execution: optional "server" or "client"` - - `type: "function"` + Whether tool search was executed by the server or by the client. - The type of tool being defined: `function` + - `"server"` - - `"function"` + - `"client"` -- `top_p: optional number` + - `status: optional "in_progress" or "completed" or "incomplete"` - 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 status of the tool search call. - We generally recommend altering this or temperature but not both. + - `"in_progress"` -### Returns + - `"completed"` -- `Assistant object { id, created_at, description, 10 more }` + - `"incomplete"` - Represents an `assistant` that can call the model and use tools. + - `ToolSearchOutput object { tools, type, id, 4 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 identifier, which can be referenced in API endpoints. + The loaded tool definitions returned by the tool search output. - - `created_at: number` + - `Function object { name, parameters, strict, 5 more }` - The Unix timestamp (in seconds) for when the assistant was created. + 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). - - `description: string` + - `name: string` - The description of the assistant. The maximum length is 512 characters. + The name of the function to call. - - `instructions: string` + - `parameters: map[unknown]` - The system instructions that the assistant uses. The maximum length is 256,000 characters. + A JSON schema object describing the parameters of the function. - - `metadata: Metadata` + - `strict: 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. + Whether strict parameter validation is enforced for this function tool. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `type: "function"` - - `model: string` + The type of the function tool. Always `function`. - ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](/docs/models) for descriptions of them. + - `"function"` - - `name: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The name of the assistant. The maximum length is 256 characters. + The tool invocation context(s). - - `object: "assistant"` + - `"direct"` - The object type, which is always `assistant`. + - `"programmatic"` - - `"assistant"` + - `defer_loading: optional boolean` - - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` + Whether this function is deferred and loaded via tool search. - A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. + - `description: optional string` - - `CodeInterpreterTool object { type }` + A description of the function. Used by the model to determine whether or not to call the function. - - `type: "code_interpreter"` + - `output_schema: optional map[unknown]` - The type of tool being defined: `code_interpreter` + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `"code_interpreter"` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `FileSearchTool object { type, file_search }` + 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 tool being defined: `file_search` + The type of the file search tool. Always `file_search`. - `"file_search"` - - `file_search: optional object { max_num_results, ranking_options }` - - Overrides for the file search tool. - - - `max_num_results: optional number` - - The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + - `vector_store_ids: array of string` - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + The IDs of the vector stores to search. - - `ranking_options: optional object { score_threshold, ranker }` + - `filters: optional object { key, type, value } or object { filters, type }` - The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + A filter to apply. - See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `ComparisonFilter object { key, type, value }` - - `score_threshold: number` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `key: string` - - `ranker: optional "auto" or "default_2024_08_21"` + The key to compare against the value. - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `type: "eq" or "ne" or "gt" or 5 more` - - `"auto"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"default_2024_08_21"` + - `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 - - `FunctionTool object { function, type }` + - `"eq"` - - `function: FunctionDefinition` + - `"ne"` - - `name: string` + - `"gt"` - The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + - `"gte"` - - `description: optional string` + - `"lt"` - A description of what the function does, used by the model to choose when and how to call the function. + - `"lte"` - - `parameters: optional FunctionParameters` + - `"in"` - The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + - `"nin"` - Omitting `parameters` defines a function with an empty parameter list. + - `value: string or number or boolean or array of string or number` - - `strict: optional boolean` + The value to compare against the attribute key; supports string, number, or boolean types. - Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-calling). + - `string` - - `type: "function"` + - `number` - The type of tool being defined: `function` + - `boolean` - - `"function"` + - `array of string or number` - - `response_format: optional AssistantResponseFormatOption` + - `string` - Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `number` - Setting to `{ "type": "json_schema", "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). + - `CompoundFilter object { filters, type }` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + Combine multiple filters using `and` or `or`. - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `filters: array of object { key, type, value } or unknown` - - `"auto"` + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - `auto` is the default value + - `ComparisonFilter object { key, type, value }` - - `"auto"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `ResponseFormatText object { type }` + - `key: string` - Default response format. Used to generate text responses. + The key to compare against the value. - - `type: "text"` + - `type: "eq" or "ne" or "gt" or 5 more` - The type of response format being defined. Always `text`. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `"text"` + - `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 - - `ResponseFormatJSONObject object { type }` + - `"eq"` - 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. + - `"ne"` - - `type: "json_object"` + - `"gt"` - The type of response format being defined. Always `json_object`. + - `"gte"` - - `"json_object"` + - `"lt"` - - `ResponseFormatJSONSchema object { json_schema, type }` + - `"lte"` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + - `"in"` - - `json_schema: object { name, description, schema, strict }` + - `"nin"` - Structured Outputs configuration options, including a JSON Schema. + - `value: string or number or boolean or array of string or number` - - `name: string` + The value to compare against the attribute key; supports string, number, or boolean types. - 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. + - `string` - - `description: optional string` + - `number` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `boolean` - - `schema: optional map[unknown]` + - `array of string or number` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `string` - - `strict: optional boolean` + - `number` - 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). + - `unknown` - - `type: "json_schema"` + - `type: "and" or "or"` - The type of response format being defined. Always `json_schema`. + Type of operation: `and` or `or`. - - `"json_schema"` + - `"and"` - - `temperature: optional number` + - `"or"` - 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. + - `max_num_results: optional number` - - `tool_resources: optional object { code_interpreter, file_search }` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `code_interpreter: optional object { file_ids }` + Ranking options for search. - - `file_ids: optional array of string` + - `hybrid_search: optional object { embedding_weight, text_weight }` - A list of [file](/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - - `file_search: optional object { vector_store_ids }` + - `embedding_weight: number` - - `vector_store_ids: optional array of string` + The weight of the embedding in the reciprocal ranking fusion. - The ID of the [vector store](/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. + - `text_weight: number` - - `top_p: optional number` + The weight of the text in the reciprocal ranking fusion. - 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. + - `ranker: optional "auto" or "default-2024-11-15"` - We generally recommend altering this or temperature but not both. + The ranker to use for the file search. -### Example + - `"auto"` -```http -curl https://api.openai.com/v1/assistants \ - -H 'Content-Type: application/json' \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "model": "gpt-4o", - "temperature": 1, - "top_p": 1 - }' -``` + - `"default-2024-11-15"` -#### Response + - `score_threshold: optional number` -```json -{ - "id": "id", - "created_at": 0, - "description": "description", - "instructions": "instructions", - "metadata": { - "foo": "string" - }, - "model": "model", - "name": "name", - "object": "assistant", - "tools": [ - { - "type": "code_interpreter" - } - ], - "response_format": "auto", - "temperature": 1, - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - }, - "top_p": 1 -} -``` + 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. -### Code Interpreter + - `Computer object { type }` -```http -curl "https://api.openai.com/v1/assistants" \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: assistants=v2" \ - -d '{ - "instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.", - "name": "Math Tutor", - "tools": [{"type": "code_interpreter"}], - "model": "gpt-4o" - }' -``` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). -#### Response + - `type: "computer"` -```json -{ - "id": "asst_abc123", - "object": "assistant", - "created_at": 1698984975, - "name": "Math Tutor", - "description": null, - "model": "gpt-4o", - "instructions": "You are a personal math tutor. When asked a question, write and run Python code to answer the question.", - "tools": [ - { - "type": "code_interpreter" - } - ], - "metadata": {}, - "top_p": 1.0, - "temperature": 1.0, - "response_format": "auto" -} -``` + The type of the computer tool. Always `computer`. -### Files + - `"computer"` -```http -curl https://api.openai.com/v1/assistants \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: assistants=v2" \ - -d '{ - "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies.", - "tools": [{"type": "file_search"}], - "tool_resources": {"file_search": {"vector_store_ids": ["vs_123"]}}, - "model": "gpt-4o" - }' -``` + - `ComputerUsePreview object { display_height, display_width, environment, type }` -#### Response + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). -```json -{ - "id": "asst_abc123", - "object": "assistant", - "created_at": 1699009403, - "name": "HR Helper", - "description": null, - "model": "gpt-4o", - "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies.", - "tools": [ - { - "type": "file_search" - } - ], - "tool_resources": { - "file_search": { - "vector_store_ids": ["vs_123"] - } - }, - "metadata": {}, - "top_p": 1.0, - "temperature": 1.0, - "response_format": "auto" -} -``` + - `display_height: number` -## Retrieve assistant + The height of the computer display. -**get** `/assistants/{assistant_id}` + - `display_width: number` -Retrieves an assistant. + The width of the computer display. -### Path Parameters + - `environment: "windows" or "mac" or "linux" or 2 more` -- `assistant_id: string` + The type of computer environment to control. -### Returns + - `"windows"` -- `Assistant object { id, created_at, description, 10 more }` + - `"mac"` - Represents an `assistant` that can call the model and use tools. + - `"linux"` - - `id: string` + - `"ubuntu"` - The identifier, which can be referenced in API endpoints. + - `"browser"` - - `created_at: number` + - `type: "computer_use_preview"` - The Unix timestamp (in seconds) for when the assistant was created. + The type of the computer use tool. Always `computer_use_preview`. - - `description: string` + - `"computer_use_preview"` - The description of the assistant. The maximum length is 512 characters. + - `WebSearch object { type, filters, search_context_size, user_location }` - - `instructions: string` + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - The system instructions that the assistant uses. The maximum length is 256,000 characters. + - `type: "web_search" or "web_search_2025_08_26"` - - `metadata: Metadata` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - 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. + - `"web_search"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"web_search_2025_08_26"` - - `model: string` + - `filters: optional object { allowed_domains }` - ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](/docs/models) for descriptions of them. + Filters for the search. - - `name: string` + - `allowed_domains: optional array of string` - The name of the assistant. The maximum length is 256 characters. + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - - `object: "assistant"` + Example: `["pubmed.ncbi.nlm.nih.gov"]` - The object type, which is 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. - - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` + - `"low"` - A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. + - `"medium"` - - `CodeInterpreterTool object { type }` + - `"high"` - - `type: "code_interpreter"` + - `user_location: optional object { city, country, region, 2 more }` - The type of tool being defined: `code_interpreter` + The approximate location of the user. - - `"code_interpreter"` + - `city: optional string` - - `FileSearchTool object { type, file_search }` + Free text input for the city of the user, e.g. `San Francisco`. - - `type: "file_search"` + - `country: optional string` - The type of tool being defined: `file_search` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"file_search"` + - `region: optional string` - - `file_search: optional object { max_num_results, ranking_options }` + Free text input for the region of the user, e.g. `California`. - Overrides for the file search tool. + - `timezone: optional string` - - `max_num_results: optional number` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + - `type: optional "approximate"` - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + The type of location approximation. Always `approximate`. - - `ranking_options: optional object { score_threshold, ranker }` + - `"approximate"` - The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + - `Mcp object { server_label, type, allowed_callers, 9 more }` - See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `score_threshold: number` + - `server_label: string` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + A label for this MCP server, used to identify it in tool calls. - - `ranker: optional "auto" or "default_2024_08_21"` + - `type: "mcp"` - The ranker to use for the file search. If not specified will use the `auto` ranker. + The type of the MCP tool. Always `mcp`. - - `"auto"` + - `"mcp"` - - `"default_2024_08_21"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `FunctionTool object { function, type }` + The tool invocation context(s). - - `function: FunctionDefinition` + - `"direct"` - - `name: string` + - `"programmatic"` - The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `description: optional string` + List of allowed tool names or a filter object. - A description of what the function does, used by the model to choose when and how to call the function. + - `McpAllowedTools = array of string` - - `parameters: optional FunctionParameters` + A string array of allowed tool names - The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + - `McpToolFilter object { read_only, tool_names }` - Omitting `parameters` defines a function with an empty parameter list. + A filter object to specify which tools are allowed. - - `strict: optional boolean` + - `read_only: optional boolean` - Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-calling). + 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: "function"` + - `tool_names: optional array of string` - The type of tool being defined: `function` + List of allowed tool names. - - `"function"` + - `authorization: optional string` - - `response_format: optional AssistantResponseFormatOption` + 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. - Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - Setting to `{ "type": "json_schema", "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). + 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). - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + Currently supported `connector_id` values are: - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - 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` - - `"auto"` + - `"connector_dropbox"` - `auto` is the default value + - `"connector_gmail"` - - `"auto"` + - `"connector_googlecalendar"` - - `ResponseFormatText object { type }` + - `"connector_googledrive"` - Default response format. Used to generate text responses. + - `"connector_microsoftteams"` - - `type: "text"` + - `"connector_outlookcalendar"` - The type of response format being defined. Always `text`. + - `"connector_outlookemail"` - - `"text"` + - `"connector_sharepoint"` - - `ResponseFormatJSONObject object { type }` + - `defer_loading: optional boolean` - 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. + Whether this MCP tool is deferred and discovered via tool search. - - `type: "json_object"` + - `headers: optional map[string]` - The type of response format being defined. Always `json_object`. + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `"json_object"` + - `require_approval: optional object { always, never } or "always" or "never"` - - `ResponseFormatJSONSchema object { json_schema, type }` + Specify which of the MCP server's tools require approval. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + - `McpToolApprovalFilter object { always, never }` - - `json_schema: object { name, description, schema, strict }` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - Structured Outputs configuration options, including a JSON Schema. + - `always: optional object { read_only, tool_names }` - - `name: string` + A filter object to specify which tools are allowed. - 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. + - `read_only: optional boolean` - - `description: 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. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `tool_names: optional array of string` - - `schema: optional map[unknown]` + List of allowed tool names. - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `never: optional object { read_only, tool_names }` - - `strict: optional boolean` + A filter object to specify which tools are allowed. - 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). + - `read_only: optional boolean` - - `type: "json_schema"` + 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 response format being defined. Always `json_schema`. + - `tool_names: optional array of string` - - `"json_schema"` + List of allowed tool names. - - `temperature: optional number` + - `McpToolApprovalSetting = "always" or "never"` - 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. + 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. - - `tool_resources: optional object { code_interpreter, file_search }` + - `"always"` - A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + - `"never"` - - `code_interpreter: optional object { file_ids }` + - `server_description: optional string` - - `file_ids: optional array of string` + Optional description of the MCP server, used to provide more context. - A list of [file](/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. + - `server_url: optional string` - - `file_search: optional object { vector_store_ids }` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `vector_store_ids: optional array of string` + - `tunnel_id: optional string` - The ID of the [vector store](/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. + 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. - - `top_p: optional number` + - `CodeInterpreter object { container, type, allowed_callers }` - 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. + A tool that runs Python code to help generate a response to a prompt. - We generally recommend altering this or temperature but not both. + - `container: string or object { type, file_ids, memory_limit, network_policy }` -### Example + 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. -```http -curl https://api.openai.com/v1/assistants/$ASSISTANT_ID \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `string` -#### Response + The container ID. -```json -{ - "id": "id", - "created_at": 0, - "description": "description", - "instructions": "instructions", - "metadata": { - "foo": "string" - }, - "model": "model", - "name": "name", - "object": "assistant", - "tools": [ - { - "type": "code_interpreter" - } - ], - "response_format": "auto", - "temperature": 1, - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - }, - "top_p": 1 -} -``` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` -### Example + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. -```http -curl https://api.openai.com/v1/assistants/asst_abc123 \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: assistants=v2" -``` + - `type: "auto"` -#### Response + Always `auto`. -```json -{ - "id": "asst_abc123", - "object": "assistant", - "created_at": 1699009709, - "name": "HR Helper", - "description": null, - "model": "gpt-4o", - "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies.", - "tools": [ - { - "type": "file_search" - } - ], - "metadata": {}, - "top_p": 1.0, - "temperature": 1.0, - "response_format": "auto" -} -``` + - `"auto"` -## Modify assistant + - `file_ids: optional array of string` -**post** `/assistants/{assistant_id}` + An optional list of uploaded files to make available to your code. -Modifies an assistant. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` -### Path Parameters + The memory limit for the code interpreter container. -- `assistant_id: string` + - `"1g"` -### Body Parameters + - `"4g"` -- `description: optional string` + - `"16g"` - The description of the assistant. The maximum length is 512 characters. + - `"64g"` -- `instructions: optional string` + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - The system instructions that the assistant uses. The maximum length is 256,000 characters. + Network access policy for the container. -- `metadata: optional Metadata` + - `BetaContainerNetworkPolicyDisabled object { 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. + - `type: "disabled"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + Disable outbound network access. Always `disabled`. -- `model: optional string or "gpt-5" or "gpt-5-mini" or "gpt-5-nano" or 39 more` + - `"disabled"` - ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](/docs/models) for descriptions of them. + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - - `string` + - `allowed_domains: array of string` - - `AssistantSupportedModels = "gpt-5" or "gpt-5-mini" or "gpt-5-nano" or 39 more` + A list of allowed domains when type is `allowlist`. - ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](/docs/models) for descriptions of them. + - `type: "allowlist"` - - `"gpt-5"` + Allow outbound network access only to specified domains. Always `allowlist`. - - `"gpt-5-mini"` + - `"allowlist"` - - `"gpt-5-nano"` + - `domain_secrets: optional array of BetaContainerNetworkPolicyDomainSecret` - - `"gpt-5-2025-08-07"` + Optional domain-scoped secrets for allowlisted domains. - - `"gpt-5-mini-2025-08-07"` + - `domain: string` - - `"gpt-5-nano-2025-08-07"` + The domain associated with the secret. - - `"gpt-4.1"` + - `name: string` - - `"gpt-4.1-mini"` + The name of the secret to inject for the domain. - - `"gpt-4.1-nano"` + - `value: string` - - `"gpt-4.1-2025-04-14"` + The secret value to inject for the domain. - - `"gpt-4.1-mini-2025-04-14"` + - `type: "code_interpreter"` - - `"gpt-4.1-nano-2025-04-14"` + The type of the code interpreter tool. Always `code_interpreter`. - - `"o3-mini"` + - `"code_interpreter"` - - `"o3-mini-2025-01-31"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"o1"` + The tool invocation context(s). - - `"o1-2024-12-17"` + - `"direct"` - - `"gpt-4o"` + - `"programmatic"` - - `"gpt-4o-2024-11-20"` + - `ProgrammaticToolCalling object { type }` - - `"gpt-4o-2024-08-06"` + - `type: "programmatic_tool_calling"` - - `"gpt-4o-2024-05-13"` + The type of the tool. Always `programmatic_tool_calling`. - - `"gpt-4o-mini"` + - `"programmatic_tool_calling"` - - `"gpt-4o-mini-2024-07-18"` + - `ImageGeneration object { type, action, background, 9 more }` - - `"gpt-4.5-preview"` + A tool that generates images using the GPT image models. - - `"gpt-4.5-preview-2025-02-27"` + - `type: "image_generation"` - - `"gpt-4-turbo"` + The type of the image generation tool. Always `image_generation`. - - `"gpt-4-turbo-2024-04-09"` + - `"image_generation"` - - `"gpt-4-0125-preview"` + - `action: optional "generate" or "edit" or "auto"` - - `"gpt-4-turbo-preview"` + Whether to generate a new image or edit an existing image. Default: `auto`. - - `"gpt-4-1106-preview"` + - `"generate"` - - `"gpt-4-vision-preview"` + - `"edit"` - - `"gpt-4"` + - `"auto"` - - `"gpt-4-0314"` + - `background: optional "transparent" or "opaque" or "auto"` - - `"gpt-4-0613"` + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `"gpt-4-32k"` + - `"transparent"` - - `"gpt-4-32k-0314"` + - `"opaque"` - - `"gpt-4-32k-0613"` + - `"auto"` - - `"gpt-3.5-turbo"` + - `input_fidelity: optional "high" or "low"` - - `"gpt-3.5-turbo-16k"` + 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`. - - `"gpt-3.5-turbo-0613"` + - `"high"` - - `"gpt-3.5-turbo-1106"` + - `"low"` - - `"gpt-3.5-turbo-0125"` + - `input_image_mask: optional object { file_id, image_url }` - - `"gpt-3.5-turbo-16k-0613"` + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). -- `name: optional string` + - `file_id: optional string` - The name of the assistant. The maximum length is 256 characters. + File ID for the mask image. -- `reasoning_effort: optional ReasoningEffort` + - `image_url: 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. + Base64-encoded mask image. - - `"none"` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `"minimal"` + The image generation model to use. Default: `gpt-image-1`. - - `"low"` + - `string` - - `"medium"` + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `"high"` + The image generation model to use. Default: `gpt-image-1`. - - `"xhigh"` + - `"gpt-image-1"` - - `"max"` + - `"gpt-image-1-mini"` -- `response_format: optional AssistantResponseFormatOption` + - `"gpt-image-1.5"` - Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `moderation: optional "auto" or "low"` - Setting to `{ "type": "json_schema", "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). + Moderation level for the generated image. Default: `auto`. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `"auto"` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `"low"` - - `"auto"` + - `output_compression: optional number` - `auto` is the default value + Compression level for the output image. Default: 100. - - `"auto"` + - `output_format: optional "png" or "webp" or "jpeg"` - - `ResponseFormatText object { type }` + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - Default response format. Used to generate text responses. + - `"png"` - - `type: "text"` + - `"webp"` - The type of response format being defined. Always `text`. + - `"jpeg"` - - `"text"` + - `partial_images: optional number` - - `ResponseFormatJSONObject object { type }` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - 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. + - `quality: optional "low" or "medium" or "high" or "auto"` - - `type: "json_object"` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - The type of response format being defined. Always `json_object`. + - `"low"` - - `"json_object"` + - `"medium"` - - `ResponseFormatJSONSchema object { json_schema, type }` + - `"high"` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + - `"auto"` - - `json_schema: object { name, description, schema, strict }` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - Structured Outputs configuration options, including a JSON Schema. + 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`. - - `name: string` + - `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. + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `description: 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`. - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `"1024x1024"` - - `schema: optional map[unknown]` + - `"1024x1536"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `"1536x1024"` - - `strict: optional boolean` + - `"auto"` - 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). + - `LocalShell object { type }` - - `type: "json_schema"` + A tool that allows the model to execute shell commands in a local environment. - The type of response format being defined. Always `json_schema`. + - `type: "local_shell"` - - `"json_schema"` + The type of the local shell tool. Always `local_shell`. -- `temperature: optional number` + - `"local_shell"` - 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. + - `Shell object { type, allowed_callers, environment }` -- `tool_resources: optional object { code_interpreter, file_search }` + A tool that allows the model to execute shell commands. - A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + - `type: "shell"` - - `code_interpreter: optional object { file_ids }` + The type of the shell tool. Always `shell`. - - `file_ids: optional array of string` + - `"shell"` - Overrides the list of [file](/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `file_search: optional object { vector_store_ids }` + The tool invocation context(s). - - `vector_store_ids: optional array of string` + - `"direct"` - Overrides the [vector store](/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. + - `"programmatic"` -- `tools: optional array of CodeInterpreterTool or FileSearchTool or FunctionTool` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `CodeInterpreterTool object { type }` + - `type: "container_auto"` - - `type: "code_interpreter"` + Automatically creates a container for this request - The type of tool being defined: `code_interpreter` + - `"container_auto"` - - `"code_interpreter"` + - `file_ids: optional array of string` - - `FileSearchTool object { type, file_search }` + An optional list of uploaded files to make available to your code. - - `type: "file_search"` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The type of tool being defined: `file_search` + The memory limit for the container. - - `"file_search"` + - `"1g"` - - `file_search: optional object { max_num_results, ranking_options }` + - `"4g"` - Overrides for the file search tool. + - `"16g"` - - `max_num_results: optional number` + - `"64g"` - The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + Network access policy for the container. - - `ranking_options: optional object { score_threshold, ranker }` + - `BetaContainerNetworkPolicyDisabled object { type }` - The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `skills: optional array of BetaSkillReference or BetaInlineSkill` - - `score_threshold: number` + An optional list of skills referenced by id or inline data. - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `BetaSkillReference object { skill_id, type, version }` - - `ranker: optional "auto" or "default_2024_08_21"` + - `skill_id: string` - The ranker to use for the file search. If not specified will use the `auto` ranker. + The ID of the referenced skill. - - `"auto"` + - `type: "skill_reference"` - - `"default_2024_08_21"` + References a skill created with the /v1/skills endpoint. - - `FunctionTool object { function, type }` + - `"skill_reference"` - - `function: FunctionDefinition` + - `version: optional string` - - `name: string` + Optional skill version. Use a positive integer or 'latest'. Omit for default. - The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + - `BetaInlineSkill object { description, name, source, type }` - - `description: optional string` + - `description: string` - A description of what the function does, used by the model to choose when and how to call the function. + The description of the skill. - - `parameters: optional FunctionParameters` + - `name: string` - The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + The name of the skill. - Omitting `parameters` defines a function with an empty parameter list. + - `source: BetaInlineSkillSource` - - `strict: optional boolean` + Inline skill payload - Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-calling). + - `data: string` - - `type: "function"` + Base64-encoded skill zip bundle. - The type of tool being defined: `function` + - `media_type: "application/zip"` - - `"function"` + The media type of the inline skill payload. Must be `application/zip`. -- `top_p: optional number` + - `"application/zip"` - 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. + - `type: "base64"` - We generally recommend altering this or temperature but not both. + The type of the inline skill source. Must be `base64`. -### Returns + - `"base64"` -- `Assistant object { id, created_at, description, 10 more }` + - `type: "inline"` - Represents an `assistant` that can call the model and use tools. + Defines an inline skill for this request. - - `id: string` + - `"inline"` - The identifier, which can be referenced in API endpoints. + - `BetaLocalEnvironment object { type, skills }` - - `created_at: number` + - `type: "local"` - The Unix timestamp (in seconds) for when the assistant was created. + Use a local computer environment. - - `description: string` + - `"local"` - The description of the assistant. The maximum length is 512 characters. + - `skills: optional array of BetaLocalSkill` - - `instructions: string` + An optional list of skills. - The system instructions that the assistant uses. The maximum length is 256,000 characters. + - `description: string` - - `metadata: Metadata` + The description of the skill. - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `name: string` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The name of the skill. - - `model: string` + - `path: string` - ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](/docs/models) for descriptions of them. + The path to the directory containing the skill. - - `name: string` + - `BetaContainerReference object { container_id, type }` - The name of the assistant. The maximum length is 256 characters. + - `container_id: string` - - `object: "assistant"` + The ID of the referenced container. - The object type, which is always `assistant`. + - `type: "container_reference"` - - `"assistant"` + References a container created with the /v1/containers endpoint - - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` + - `"container_reference"` - A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. + - `Custom object { name, type, allowed_callers, 3 more }` - - `CodeInterpreterTool object { type }` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `type: "code_interpreter"` + - `name: string` - The type of tool being defined: `code_interpreter` + The name of the custom tool, used to identify it in tool calls. - - `"code_interpreter"` + - `type: "custom"` - - `FileSearchTool object { type, file_search }` + The type of the custom tool. Always `custom`. - - `type: "file_search"` + - `"custom"` - The type of tool being defined: `file_search` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"file_search"` + The tool invocation context(s). - - `file_search: optional object { max_num_results, ranking_options }` + - `"direct"` - Overrides for the file search tool. + - `"programmatic"` - - `max_num_results: optional number` + - `defer_loading: optional boolean` - The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + Whether this tool should be deferred and discovered via tool search. - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `description: optional string` - - `ranking_options: optional object { score_threshold, ranker }` + Optional description of the custom tool, used to provide more context. - The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + - `format: optional object { type } or object { definition, syntax, type }` - See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + The input format for the custom tool. Default is unconstrained text. - - `score_threshold: number` + - `Text object { type }` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + Unconstrained free-form text. - - `ranker: optional "auto" or "default_2024_08_21"` + - `type: "text"` - The ranker to use for the file search. If not specified will use the `auto` ranker. + Unconstrained text format. Always `text`. - - `"auto"` + - `"text"` - - `"default_2024_08_21"` + - `Grammar object { definition, syntax, type }` - - `FunctionTool object { function, type }` + A grammar defined by the user. - - `function: FunctionDefinition` + - `definition: string` - - `name: string` + The grammar definition. - The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + - `syntax: "lark" or "regex"` - - `description: optional string` + The syntax of the grammar definition. One of `lark` or `regex`. - A description of what the function does, used by the model to choose when and how to call the function. + - `"lark"` - - `parameters: optional FunctionParameters` + - `"regex"` - The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + - `type: "grammar"` - Omitting `parameters` defines a function with an empty parameter list. + Grammar format. Always `grammar`. - - `strict: optional boolean` + - `"grammar"` - Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-calling). + - `Namespace object { description, name, tools, type }` - - `type: "function"` + Groups function/custom tools under a shared namespace. - The type of tool being defined: `function` + - `description: string` - - `"function"` + A description of the namespace shown to the model. - - `response_format: optional AssistantResponseFormatOption` + - `name: string` - Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + The namespace name used in tool calls (for example, `crm`). - Setting to `{ "type": "json_schema", "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). + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + The function/custom tools available inside this namespace. - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `Function object { name, type, allowed_callers, 5 more }` - - `"auto"` + - `name: string` - `auto` is the default value + - `type: "function"` - - `"auto"` + - `"function"` - - `ResponseFormatText object { type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - Default response format. Used to generate text responses. + The tool invocation context(s). - - `type: "text"` + - `"direct"` - The type of response format being defined. Always `text`. + - `"programmatic"` - - `"text"` + - `defer_loading: optional boolean` - - `ResponseFormatJSONObject object { type }` + Whether this function should be deferred and discovered via tool search. - 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. + - `description: optional string` - - `type: "json_object"` + - `output_schema: optional map[unknown]` - The type of response format being defined. Always `json_object`. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `"json_object"` + - `parameters: optional unknown` - - `ResponseFormatJSONSchema object { json_schema, type }` + - `strict: optional boolean` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + 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. - - `json_schema: object { name, description, schema, strict }` + - `Custom object { name, type, allowed_callers, 3 more }` - Structured Outputs configuration options, including a JSON Schema. + 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 response format. Must be a-z, A-Z, 0-9, or contain - underscores and dashes, with a maximum length of 64. + The name of the custom tool, used to identify it in tool calls. - - `description: optional string` + - `type: "custom"` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The type of the custom tool. Always `custom`. - - `schema: optional map[unknown]` + - `"custom"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `allowed_callers: optional array of "direct" or "programmatic"` - - `strict: optional boolean` + The tool invocation context(s). - 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). + - `"direct"` - - `type: "json_schema"` + - `"programmatic"` - The type of response format being defined. Always `json_schema`. + - `defer_loading: optional boolean` - - `"json_schema"` + Whether this tool should be deferred and discovered via tool search. - - `temperature: optional number` + - `description: optional 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. + Optional description of the custom tool, used to provide more context. - - `tool_resources: optional object { code_interpreter, file_search }` + - `format: optional object { type } or object { definition, syntax, type }` - A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + The input format for the custom tool. Default is unconstrained text. - - `code_interpreter: optional object { file_ids }` + - `Text object { type }` - - `file_ids: optional array of string` + Unconstrained free-form text. - A list of [file](/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. + - `type: "text"` - - `file_search: optional object { vector_store_ids }` + Unconstrained text format. Always `text`. - - `vector_store_ids: optional array of string` + - `"text"` - The ID of the [vector store](/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. + - `Grammar object { definition, syntax, type }` - - `top_p: optional number` + A grammar defined by the user. - 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. + - `definition: string` - We generally recommend altering this or temperature but not both. + The grammar definition. -### Example + - `syntax: "lark" or "regex"` -```http -curl https://api.openai.com/v1/assistants/$ASSISTANT_ID \ - -H 'Content-Type: application/json' \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "temperature": 1, - "top_p": 1 - }' -``` + The syntax of the grammar definition. One of `lark` or `regex`. -#### Response + - `"lark"` -```json -{ - "id": "id", - "created_at": 0, - "description": "description", - "instructions": "instructions", - "metadata": { - "foo": "string" - }, - "model": "model", - "name": "name", - "object": "assistant", - "tools": [ - { - "type": "code_interpreter" - } - ], - "response_format": "auto", - "temperature": 1, - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "string" - ] - }, - "file_search": { - "vector_store_ids": [ - "string" - ] - } - }, - "top_p": 1 -} -``` + - `"regex"` -### Example + - `type: "grammar"` -```http -curl https://api.openai.com/v1/assistants/asst_abc123 \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: assistants=v2" \ - -d '{ - "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.", - "tools": [{"type": "file_search"}], - "model": "gpt-4o" - }' -``` + Grammar format. Always `grammar`. -#### Response + - `"grammar"` -```json -{ - "id": "asst_123", - "object": "assistant", - "created_at": 1699009709, - "name": "HR Helper", - "description": null, - "model": "gpt-4o", - "instructions": "You are an HR bot, and you have access to files to answer employee questions about company policies. Always response with info from either of the files.", - "tools": [ - { - "type": "file_search" - } - ], - "tool_resources": { - "file_search": { - "vector_store_ids": [] - } - }, - "metadata": {}, - "top_p": 1.0, - "temperature": 1.0, - "response_format": "auto" -} -``` + - `type: "namespace"` -## Delete assistant + The type of the tool. Always `namespace`. -**delete** `/assistants/{assistant_id}` + - `"namespace"` -Delete an assistant. + - `ToolSearch object { type, description, execution, parameters }` -### Path Parameters + Hosted or BYOT tool search configuration for deferred tools. -- `assistant_id: string` + - `type: "tool_search"` -### Returns + The type of the tool. Always `tool_search`. -- `AssistantDeleted object { id, deleted, object }` + - `"tool_search"` - - `id: string` + - `description: optional string` - - `deleted: boolean` + Description shown to the model for a client-executed tool search tool. - - `object: "assistant.deleted"` + - `execution: optional "server" or "client"` - - `"assistant.deleted"` + Whether tool search is executed by the server or by the client. -### Example + - `"server"` -```http -curl https://api.openai.com/v1/assistants/$ASSISTANT_ID \ - -X DELETE \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `"client"` -#### Response + - `parameters: optional unknown` -```json -{ - "id": "id", - "deleted": true, - "object": "assistant.deleted" -} -``` + Parameter schema for a client-executed tool search tool. -### Example + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` -```http -curl https://api.openai.com/v1/assistants/asst_abc123 \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: assistants=v2" \ - -X DELETE -``` + 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). -#### Response + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` -```json -{ - "id": "asst_abc123", - "object": "assistant.deleted", - "deleted": true -} -``` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. -## Domain Types + - `"web_search_preview"` -### Assistant + - `"web_search_preview_2025_03_11"` -- `Assistant object { id, created_at, description, 10 more }` + - `search_content_types: optional array of "text" or "image"` - Represents an `assistant` that can call the model and use tools. + - `"text"` - - `id: string` + - `"image"` - The identifier, which can be referenced in API endpoints. + - `search_context_size: optional "low" or "medium" or "high"` - - `created_at: number` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - The Unix timestamp (in seconds) for when the assistant was created. + - `"low"` - - `description: string` + - `"medium"` - The description of the assistant. The maximum length is 512 characters. + - `"high"` - - `instructions: string` + - `user_location: optional object { type, city, country, 2 more }` - The system instructions that the assistant uses. The maximum length is 256,000 characters. + The user's location. - - `metadata: Metadata` + - `type: "approximate"` - 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 type of location approximation. Always `approximate`. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"approximate"` - - `model: string` + - `city: optional string` - ID of the model to use. You can use the [List models](/docs/api-reference/models/list) API to see all of your available models, or see our [Model overview](/docs/models) for descriptions of them. + Free text input for the city of the user, e.g. `San Francisco`. - - `name: string` + - `country: optional string` - The name of the assistant. The maximum length is 256 characters. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `object: "assistant"` + - `region: optional string` - The object type, which is always `assistant`. + Free text input for the region of the user, e.g. `California`. - - `"assistant"` + - `timezone: optional string` - - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - A list of tool enabled on the assistant. There can be a maximum of 128 tools per assistant. Tools can be of types `code_interpreter`, `file_search`, or `function`. + - `ApplyPatch object { type, allowed_callers }` - - `CodeInterpreterTool object { type }` + Allows the assistant to create, delete, or update files using unified diffs. - - `type: "code_interpreter"` + - `type: "apply_patch"` - The type of tool being defined: `code_interpreter` + The type of the tool. Always `apply_patch`. - - `"code_interpreter"` + - `"apply_patch"` - - `FileSearchTool object { type, file_search }` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "file_search"` + The tool invocation context(s). - The type of tool being defined: `file_search` + - `"direct"` - - `"file_search"` + - `"programmatic"` - - `file_search: optional object { max_num_results, ranking_options }` + - `type: "tool_search_output"` - Overrides for the file search tool. + The item type. Always `tool_search_output`. - - `max_num_results: optional number` + - `"tool_search_output"` - The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + - `id: optional string` - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + The unique ID of this tool search output. - - `ranking_options: optional object { score_threshold, ranker }` + - `agent: optional object { agent_name }` - The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + The agent that produced this item. - See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `agent_name: string` - - `score_threshold: number` + The canonical name of the agent that produced this item. - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `call_id: optional string` - - `ranker: optional "auto" or "default_2024_08_21"` + The unique ID of the tool search call generated by the model. - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `execution: optional "server" or "client"` - - `"auto"` + Whether tool search was executed by the server or by the client. - - `"default_2024_08_21"` + - `"server"` - - `FunctionTool object { function, type }` + - `"client"` - - `function: FunctionDefinition` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `name: string` + The status of the tool search output. - The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + - `"in_progress"` - - `description: optional string` + - `"completed"` - A description of what the function does, used by the model to choose when and how to call the function. + - `"incomplete"` - - `parameters: optional FunctionParameters` + - `AdditionalTools object { role, tools, type, 2 more }` - The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + - `role: "developer"` - Omitting `parameters` defines a function with an empty parameter list. + The role that provided the additional tools. Only `developer` is supported. - - `strict: optional boolean` + - `"developer"` - Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-calling). + - `tools: array of object { name, parameters, strict, 5 more } or object { type, vector_store_ids, filters, 2 more } or object { type } or 13 more` - - `type: "function"` + A list of additional tools made available at this item. - The type of tool being defined: `function` + - `Function object { name, parameters, strict, 5 more }` - - `"function"` + 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). - - `response_format: optional AssistantResponseFormatOption` + - `name: string` - Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + The name of the function to call. - Setting to `{ "type": "json_schema", "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). + - `parameters: map[unknown]` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + A JSON schema object describing the parameters of the function. - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `strict: boolean` - - `"auto"` + Whether strict parameter validation is enforced for this function tool. - `auto` is the default value + - `type: "function"` - - `"auto"` + The type of the function tool. Always `function`. - - `ResponseFormatText object { type }` + - `"function"` - Default response format. Used to generate text responses. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `type: "text"` + The tool invocation context(s). - The type of response format being defined. Always `text`. + - `"direct"` - - `"text"` + - `"programmatic"` - - `ResponseFormatJSONObject object { type }` + - `defer_loading: optional boolean` - 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. + Whether this function is deferred and loaded via tool search. - - `type: "json_object"` + - `description: optional string` - The type of response format being defined. Always `json_object`. + A description of the function. Used by the model to determine whether or not to call the function. - - `"json_object"` + - `output_schema: optional map[unknown]` - - `ResponseFormatJSONSchema object { json_schema, type }` + A JSON schema object describing the JSON value encoded in string outputs for this function. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `json_schema: object { name, description, schema, strict }` + 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). - Structured Outputs configuration options, including a JSON Schema. + - `type: "file_search"` - - `name: string` + The type of the file search tool. Always `file_search`. - 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. + - `"file_search"` - - `description: optional string` + - `vector_store_ids: array of string` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The IDs of the vector stores to search. - - `schema: optional map[unknown]` + - `filters: optional object { key, type, value } or object { filters, type }` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + A filter to apply. - - `strict: optional boolean` + - `ComparisonFilter object { key, type, value }` - 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). + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `type: "json_schema"` + - `key: string` - The type of response format being defined. Always `json_schema`. + The key to compare against the value. - - `"json_schema"` + - `type: "eq" or "ne" or "gt" or 5 more` - - `temperature: optional number` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - 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. + - `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 - - `tool_resources: optional object { code_interpreter, file_search }` + - `"eq"` - A set of resources that are used by the assistant's tools. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + - `"ne"` - - `code_interpreter: optional object { file_ids }` + - `"gt"` - - `file_ids: optional array of string` + - `"gte"` - A list of [file](/docs/api-reference/files) IDs made available to the `code_interpreter`` tool. There can be a maximum of 20 files associated with the tool. + - `"lt"` - - `file_search: optional object { vector_store_ids }` + - `"lte"` - - `vector_store_ids: optional array of string` + - `"in"` - The ID of the [vector store](/docs/api-reference/vector-stores/object) attached to this assistant. There can be a maximum of 1 vector store attached to the assistant. + - `"nin"` - - `top_p: optional number` + - `value: string or number or boolean or array of string or 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 value to compare against the attribute key; supports string, number, or boolean types. - We generally recommend altering this or temperature but not both. + - `string` -### Assistant Deleted + - `number` -- `AssistantDeleted object { id, deleted, object }` + - `boolean` - - `id: string` + - `array of string or number` - - `deleted: boolean` + - `string` - - `object: "assistant.deleted"` + - `number` - - `"assistant.deleted"` + - `CompoundFilter object { filters, type }` -### Assistant Stream Event + Combine multiple filters using `and` or `or`. -- `AssistantStreamEvent = object { data, event, enabled } or object { data, event } or object { data, event } or 22 more` + - `filters: array of object { key, type, value } or unknown` - Represents an event emitted when streaming a Run. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - Each event in a server-sent events stream has an `event` and `data` property: + - `ComparisonFilter object { key, type, value }` - ``` - event: thread.created - data: {"id": "thread_123", "object": "thread", ...} - ``` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - We emit events whenever a new object is created, transitions to a new state, or is being - streamed in parts (deltas). For example, we emit `thread.run.created` when a new run - is created, `thread.run.completed` when a run completes, and so on. When an Assistant chooses - to create a message during a run, we emit a `thread.message.created event`, a - `thread.message.in_progress` event, many `thread.message.delta` events, and finally a - `thread.message.completed` event. + - `key: string` - We may add additional events over time, so we recommend handling unknown events gracefully - in your code. See the [Assistants API quickstart](/docs/assistants/overview) to learn how to - integrate the Assistants API with streaming. + The key to compare against the value. - - `object { data, event, enabled }` + - `type: "eq" or "ne" or "gt" or 5 more` - Occurs when a new [thread](/docs/api-reference/threads/object) is created. + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `data: Thread` + - `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 - Represents a thread that contains [messages](/docs/api-reference/messages). + - `"eq"` - - `id: string` + - `"ne"` - The identifier, which can be referenced in API endpoints. + - `"gt"` - - `created_at: number` + - `"gte"` - The Unix timestamp (in seconds) for when the thread was created. + - `"lt"` - - `metadata: Metadata` + - `"lte"` - 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. + - `"in"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"nin"` - - `object: "thread"` + - `value: string or number or boolean or array of string or number` - The object type, which is always `thread`. + The value to compare against the attribute key; supports string, number, or boolean types. - - `"thread"` + - `string` - - `tool_resources: object { code_interpreter, file_search }` + - `number` - A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. + - `boolean` - - `code_interpreter: optional object { file_ids }` + - `array of string or number` - - `file_ids: optional array of string` + - `string` - A list of [file](/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. + - `number` - - `file_search: optional object { vector_store_ids }` + - `unknown` - - `vector_store_ids: optional array of string` + - `type: "and" or "or"` - The [vector store](/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. + Type of operation: `and` or `or`. - - `event: "thread.created"` + - `"and"` - - `"thread.created"` + - `"or"` - - `enabled: optional boolean` + - `max_num_results: optional number` - Whether to enable input audio transcription. + The maximum number of results to return. This number should be between 1 and 50 inclusive. - - `object { data, event }` + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - Occurs when a new [run](/docs/api-reference/runs/object) is created. + Ranking options for search. - - `data: Run` + - `hybrid_search: optional object { embedding_weight, text_weight }` - Represents an execution run on a [thread](/docs/api-reference/threads). + 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 identifier, which can be referenced in API endpoints. + The weight of the embedding in the reciprocal ranking fusion. - - `assistant_id: string` + - `text_weight: number` - The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. + The weight of the text in the reciprocal ranking fusion. - - `cancelled_at: number` + - `ranker: optional "auto" or "default-2024-11-15"` - The Unix timestamp (in seconds) for when the run was cancelled. + The ranker to use for the file search. - - `completed_at: number` + - `"auto"` - The Unix timestamp (in seconds) for when the run was completed. + - `"default-2024-11-15"` - - `created_at: number` + - `score_threshold: optional number` - The Unix timestamp (in seconds) for when the run was created. + 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. - - `expires_at: number` + - `Computer object { type }` - The Unix timestamp (in seconds) for when the run will expire. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `failed_at: number` + - `type: "computer"` - The Unix timestamp (in seconds) for when the run failed. + The type of the computer tool. Always `computer`. - - `incomplete_details: object { reason }` + - `"computer"` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `ComputerUsePreview object { display_height, display_width, environment, type }` - - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `display_height: number` - - `"max_completion_tokens"` + The height of the computer display. - - `"max_prompt_tokens"` + - `display_width: number` - - `instructions: string` + The width of the computer display. - The instructions that the [assistant](/docs/api-reference/assistants) used for this run. + - `environment: "windows" or "mac" or "linux" or 2 more` - - `last_error: object { code, message }` + The type of computer environment to control. - The last error associated with this run. Will be `null` if there are no errors. + - `"windows"` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` + - `"mac"` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `"linux"` - - `"server_error"` + - `"ubuntu"` - - `"rate_limit_exceeded"` + - `"browser"` - - `"invalid_prompt"` + - `type: "computer_use_preview"` - - `message: string` + The type of the computer use tool. Always `computer_use_preview`. - A human-readable description of the error. + - `"computer_use_preview"` - - `max_completion_tokens: number` + - `WebSearch object { type, filters, search_context_size, user_location }` - The maximum number of completion tokens specified to have been used over the course of the run. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `max_prompt_tokens: number` + - `type: "web_search" or "web_search_2025_08_26"` - The maximum number of prompt tokens specified to have been used over the course of the run. + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - - `metadata: Metadata` + - `"web_search"` - 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. + - `"web_search_2025_08_26"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `filters: optional object { allowed_domains }` - - `model: string` + Filters for the search. - The model that the [assistant](/docs/api-reference/assistants) used for this run. + - `allowed_domains: optional array of string` - - `object: "thread.run"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - The object type, which is always `thread.run`. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `"thread.run"` + - `search_context_size: optional "low" or "medium" or "high"` - - `parallel_tool_calls: boolean` + 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. - Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `"low"` - - `required_action: object { submit_tool_outputs, type }` + - `"medium"` - Details on the action required to continue the run. Will be `null` if no action is required. + - `"high"` - - `submit_tool_outputs: object { tool_calls }` + - `user_location: optional object { city, country, region, 2 more }` - Details on the tool outputs needed for this run to continue. + The approximate location of the user. - - `tool_calls: array of RequiredActionFunctionToolCall` + - `city: optional string` - A list of the relevant tool calls. + Free text input for the city of the user, e.g. `San Francisco`. - - `id: string` + - `country: optional string` - The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](/docs/api-reference/runs/submitToolOutputs) endpoint. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `function: object { arguments, name }` + - `region: optional string` - The function definition. + Free text input for the region of the user, e.g. `California`. - - `arguments: string` + - `timezone: optional string` - The arguments that the model expects you to pass to the function. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `name: string` + - `type: optional "approximate"` - The name of the function. + The type of location approximation. Always `approximate`. - - `type: "function"` + - `"approximate"` - The type of tool call the output is required for. For now, this is always `function`. + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `"function"` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - - `type: "submit_tool_outputs"` + - `server_label: string` - For now, this is always `submit_tool_outputs`. + A label for this MCP server, used to identify it in tool calls. - - `"submit_tool_outputs"` + - `type: "mcp"` - - `response_format: AssistantResponseFormatOption` + The type of the MCP tool. Always `mcp`. - Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `"mcp"` - Setting to `{ "type": "json_schema", "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). + - `allowed_callers: optional array of "direct" or "programmatic"` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + The tool invocation context(s). - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `"direct"` - - `"auto"` + - `"programmatic"` - `auto` is the default value + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `"auto"` + List of allowed tool names or a filter object. - - `ResponseFormatText object { type }` + - `McpAllowedTools = array of string` - Default response format. Used to generate text responses. + A string array of allowed tool names - - `type: "text"` + - `McpToolFilter object { read_only, tool_names }` - The type of response format being defined. Always `text`. + A filter object to specify which tools are allowed. - - `"text"` + - `read_only: optional boolean` - - `ResponseFormatJSONObject 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. - 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. + - `tool_names: optional array of string` - - `type: "json_object"` + List of allowed tool names. - The type of response format being defined. Always `json_object`. + - `authorization: optional string` - - `"json_object"` + 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. - - `ResponseFormatJSONSchema object { json_schema, type }` + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + 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). - - `json_schema: object { name, description, schema, strict }` + Currently supported `connector_id` values are: - Structured Outputs configuration options, including a JSON Schema. + - 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` - - `name: string` + - `"connector_dropbox"` - 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. + - `"connector_gmail"` - - `description: optional string` + - `"connector_googlecalendar"` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `"connector_googledrive"` - - `schema: optional map[unknown]` + - `"connector_microsoftteams"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `"connector_outlookcalendar"` - - `strict: optional boolean` + - `"connector_outlookemail"` - 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). + - `"connector_sharepoint"` - - `type: "json_schema"` + - `defer_loading: optional boolean` - The type of response format being defined. Always `json_schema`. + Whether this MCP tool is deferred and discovered via tool search. - - `"json_schema"` + - `headers: optional map[string]` - - `started_at: number` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - The Unix timestamp (in seconds) for when the run was started. + - `require_approval: optional object { always, never } or "always" or "never"` - - `status: "queued" or "in_progress" or "requires_action" or 6 more` + Specify which of the MCP server's tools require approval. - The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + - `McpToolApprovalFilter object { always, never }` - - `"queued"` + 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 }` - - `"requires_action"` + A filter object to specify which tools are allowed. - - `"cancelling"` + - `read_only: optional boolean` - - `"cancelled"` + 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. - - `"failed"` + - `tool_names: optional array of string` - - `"completed"` + List of allowed tool names. - - `"incomplete"` + - `never: optional object { read_only, tool_names }` - - `"expired"` + A filter object to specify which tools are allowed. - - `thread_id: string` + - `read_only: optional boolean` - The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. + Indicates whether or not a tool modifies data or is read-only. If an + MCP server is [annotated with `readOnlyHint`](https://modelcontextprotocol.io/specification/2025-06-18/schema#toolannotations-readonlyhint), + it will match this filter. - - `tool_choice: AssistantToolChoiceOption` + - `tool_names: optional array of string` - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + List of allowed tool names. - - `"none" or "auto" or "required"` + - `McpToolApprovalSetting = "always" or "never"` + + Specify a single approval policy for all tools. One of `always` or + `never`. When set to `always`, all tools will require approval. When + set to `never`, all tools will not require approval. - `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. + - `"always"` - - `"none"` + - `"never"` - - `"auto"` + - `server_description: optional string` - - `"required"` + Optional description of the MCP server, used to provide more context. - - `AssistantToolChoice object { type, function }` + - `server_url: optional string` - Specifies a tool the model should use. Use to force the model to call a specific tool. + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `type: "function" or "code_interpreter" or "file_search"` + - `tunnel_id: optional string` - The type of the tool. If type is `function`, the function name must be set + 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. - - `"function"` + - `CodeInterpreter object { container, type, allowed_callers }` - - `"code_interpreter"` + A tool that runs Python code to help generate a response to a prompt. - - `"file_search"` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - - `function: optional AssistantToolChoiceFunction` + 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. - - `name: string` + - `string` - The name of the function to call. + The container ID. - - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `CodeInterpreterTool object { type }` + - `type: "auto"` - - `type: "code_interpreter"` + Always `auto`. - The type of tool being defined: `code_interpreter` + - `"auto"` - - `"code_interpreter"` + - `file_ids: optional array of string` - - `FileSearchTool object { type, file_search }` + An optional list of uploaded files to make available to your code. - - `type: "file_search"` + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - The type of tool being defined: `file_search` + The memory limit for the code interpreter container. - - `"file_search"` + - `"1g"` - - `file_search: optional object { max_num_results, ranking_options }` + - `"4g"` - Overrides for the file search tool. + - `"16g"` - - `max_num_results: optional number` + - `"64g"` - The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + Network access policy for the container. - - `ranking_options: optional object { score_threshold, ranker }` + - `BetaContainerNetworkPolicyDisabled object { type }` - The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `type: "code_interpreter"` - - `score_threshold: number` + The type of the code interpreter tool. Always `code_interpreter`. - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `"code_interpreter"` - - `ranker: optional "auto" or "default_2024_08_21"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The ranker to use for the file search. If not specified will use the `auto` ranker. + The tool invocation context(s). - - `"auto"` + - `"direct"` - - `"default_2024_08_21"` + - `"programmatic"` - - `FunctionTool object { function, type }` + - `ProgrammaticToolCalling object { type }` - - `function: FunctionDefinition` + - `type: "programmatic_tool_calling"` - - `name: string` + The type of the tool. Always `programmatic_tool_calling`. - The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + - `"programmatic_tool_calling"` - - `description: optional string` + - `ImageGeneration object { type, action, background, 9 more }` - A description of what the function does, used by the model to choose when and how to call the function. + A tool that generates images using the GPT image models. - - `parameters: optional FunctionParameters` + - `type: "image_generation"` - The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + The type of the image generation tool. Always `image_generation`. - Omitting `parameters` defines a function with an empty parameter list. + - `"image_generation"` - - `strict: optional boolean` + - `action: optional "generate" or "edit" or "auto"` - Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-calling). + Whether to generate a new image or edit an existing image. Default: `auto`. - - `type: "function"` + - `"generate"` - The type of tool being defined: `function` + - `"edit"` - - `"function"` + - `"auto"` - - `truncation_strategy: object { type, last_messages }` + - `background: optional "transparent" or "opaque" or "auto"` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `type: "auto" or "last_messages"` + - `"transparent"` - The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + - `"opaque"` - `"auto"` - - `"last_messages"` - - - `last_messages: optional number` + - `input_fidelity: optional "high" or "low"` - The number of most recent messages from the thread when constructing the context for the run. + 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`. - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `"high"` - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + - `"low"` - - `completion_tokens: number` + - `input_image_mask: optional object { file_id, image_url }` - Number of completion tokens used over the course of the run. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `prompt_tokens: number` + - `file_id: optional string` - Number of prompt tokens used over the course of the run. + File ID for the mask image. - - `total_tokens: number` + - `image_url: optional string` - Total number of tokens used (prompt + completion). + Base64-encoded mask image. - - `temperature: optional number` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The sampling temperature used for this run. If not set, defaults to 1. + The image generation model to use. Default: `gpt-image-1`. - - `top_p: optional number` + - `string` - The nucleus sampling value used for this run. If not set, defaults to 1. + - `"gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - - `event: "thread.run.created"` + The image generation model to use. Default: `gpt-image-1`. - - `"thread.run.created"` + - `"gpt-image-1"` - - `object { data, event }` + - `"gpt-image-1-mini"` - Occurs when a [run](/docs/api-reference/runs/object) moves to a `queued` status. + - `"gpt-image-1.5"` - - `data: Run` + - `moderation: optional "auto" or "low"` - Represents an execution run on a [thread](/docs/api-reference/threads). + Moderation level for the generated image. Default: `auto`. - - `event: "thread.run.queued"` + - `"auto"` - - `"thread.run.queued"` + - `"low"` - - `object { data, event }` + - `output_compression: optional number` - Occurs when a [run](/docs/api-reference/runs/object) moves to an `in_progress` status. + Compression level for the output image. Default: 100. - - `data: Run` + - `output_format: optional "png" or "webp" or "jpeg"` - Represents an execution run on a [thread](/docs/api-reference/threads). + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - - `event: "thread.run.in_progress"` + - `"png"` - - `"thread.run.in_progress"` + - `"webp"` - - `object { data, event }` + - `"jpeg"` - Occurs when a [run](/docs/api-reference/runs/object) moves to a `requires_action` status. + - `partial_images: optional number` - - `data: Run` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - Represents an execution run on a [thread](/docs/api-reference/threads). + - `quality: optional "low" or "medium" or "high" or "auto"` - - `event: "thread.run.requires_action"` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - - `"thread.run.requires_action"` + - `"low"` - - `object { data, event }` + - `"medium"` - Occurs when a [run](/docs/api-reference/runs/object) is completed. + - `"high"` - - `data: Run` + - `"auto"` - Represents an execution run on a [thread](/docs/api-reference/threads). + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - - `event: "thread.run.completed"` + 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`. - - `"thread.run.completed"` + - `string` - - `object { data, event }` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - Occurs when a [run](/docs/api-reference/runs/object) ends with status `incomplete`. + 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`. - - `data: Run` + - `"1024x1024"` - Represents an execution run on a [thread](/docs/api-reference/threads). + - `"1024x1536"` - - `event: "thread.run.incomplete"` + - `"1536x1024"` - - `"thread.run.incomplete"` + - `"auto"` - - `object { data, event }` + - `LocalShell object { type }` - Occurs when a [run](/docs/api-reference/runs/object) fails. + A tool that allows the model to execute shell commands in a local environment. - - `data: Run` + - `type: "local_shell"` - Represents an execution run on a [thread](/docs/api-reference/threads). + The type of the local shell tool. Always `local_shell`. - - `event: "thread.run.failed"` + - `"local_shell"` - - `"thread.run.failed"` + - `Shell object { type, allowed_callers, environment }` - - `object { data, event }` + A tool that allows the model to execute shell commands. - Occurs when a [run](/docs/api-reference/runs/object) moves to a `cancelling` status. + - `type: "shell"` - - `data: Run` + The type of the shell tool. Always `shell`. - Represents an execution run on a [thread](/docs/api-reference/threads). + - `"shell"` - - `event: "thread.run.cancelling"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"thread.run.cancelling"` + The tool invocation context(s). - - `object { data, event }` + - `"direct"` - Occurs when a [run](/docs/api-reference/runs/object) is cancelled. + - `"programmatic"` - - `data: Run` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - Represents an execution run on a [thread](/docs/api-reference/threads). + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `event: "thread.run.cancelled"` + - `BetaLocalEnvironment object { type, skills }` - - `"thread.run.cancelled"` + - `BetaContainerReference object { container_id, type }` - - `object { data, event }` + - `Custom object { name, type, allowed_callers, 3 more }` - Occurs when a [run](/docs/api-reference/runs/object) expires. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `data: Run` + - `name: string` - Represents an execution run on a [thread](/docs/api-reference/threads). + The name of the custom tool, used to identify it in tool calls. - - `event: "thread.run.expired"` + - `type: "custom"` - - `"thread.run.expired"` + The type of the custom tool. Always `custom`. - - `object { data, event }` + - `"custom"` - Occurs when a [run step](/docs/api-reference/run-steps/step-object) is created. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `data: RunStep` + The tool invocation context(s). - Represents a step in execution of a run. + - `"direct"` - - `id: string` + - `"programmatic"` - The identifier of the run step, which can be referenced in API endpoints. + - `defer_loading: optional boolean` - - `assistant_id: string` + Whether this tool should be deferred and discovered via tool search. - The ID of the [assistant](/docs/api-reference/assistants) associated with the run step. + - `description: optional string` - - `cancelled_at: number` + Optional description of the custom tool, used to provide more context. - The Unix timestamp (in seconds) for when the run step was cancelled. + - `format: optional object { type } or object { definition, syntax, type }` - - `completed_at: number` + The input format for the custom tool. Default is unconstrained text. - The Unix timestamp (in seconds) for when the run step completed. + - `Text object { type }` - - `created_at: number` + Unconstrained free-form text. - The Unix timestamp (in seconds) for when the run step was created. + - `type: "text"` - - `expired_at: number` + Unconstrained text format. Always `text`. - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + - `"text"` - - `failed_at: number` + - `Grammar object { definition, syntax, type }` - The Unix timestamp (in seconds) for when the run step failed. + A grammar defined by the user. - - `last_error: object { code, message }` + - `definition: string` - The last error associated with this run step. Will be `null` if there are no errors. + The grammar definition. - - `code: "server_error" or "rate_limit_exceeded"` + - `syntax: "lark" or "regex"` - One of `server_error` or `rate_limit_exceeded`. + The syntax of the grammar definition. One of `lark` or `regex`. - - `"server_error"` + - `"lark"` - - `"rate_limit_exceeded"` + - `"regex"` - - `message: string` + - `type: "grammar"` - A human-readable description of the error. + Grammar format. Always `grammar`. - - `metadata: Metadata` + - `"grammar"` - 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. + - `Namespace object { description, name, tools, type }` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + Groups function/custom tools under a shared namespace. - - `object: "thread.run.step"` + - `description: string` - The object type, which is always `thread.run.step`. + A description of the namespace shown to the model. - - `"thread.run.step"` + - `name: string` - - `run_id: string` + The namespace name used in tool calls (for example, `crm`). - The ID of the [run](/docs/api-reference/runs) that this run step is a part of. + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - - `status: "in_progress" or "cancelled" or "failed" or 2 more` + The function/custom tools available inside this namespace. - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + - `Function object { name, type, allowed_callers, 5 more }` - - `"in_progress"` + - `name: string` - - `"cancelled"` + - `type: "function"` - - `"failed"` + - `"function"` - - `"completed"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"expired"` + The tool invocation context(s). - - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` + - `"direct"` - The details of the run step. + - `"programmatic"` - - `MessageCreationStepDetails object { message_creation, type }` + - `defer_loading: optional boolean` - Details of the message creation by the run step. + Whether this function should be deferred and discovered via tool search. - - `message_creation: object { message_id }` + - `description: optional string` - - `message_id: string` + - `output_schema: optional map[unknown]` - The ID of the message that was created by this run step. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - - `type: "message_creation"` + - `parameters: optional unknown` - Always `message_creation`. + - `strict: optional boolean` - - `"message_creation"` + 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. - - `ToolCallsStepDetails object { tool_calls, type }` + - `Custom object { name, type, allowed_callers, 3 more }` - Details of the tool call. + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `tool_calls: array of CodeInterpreterToolCall or FileSearchToolCall or FunctionToolCall` + - `name: string` - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + The name of the custom tool, used to identify it in tool calls. - - `CodeInterpreterToolCall object { id, code_interpreter, type }` + - `type: "custom"` - Details of the Code Interpreter tool call the run step was involved in. + The type of the custom tool. Always `custom`. - - `id: string` + - `"custom"` - The ID of the tool call. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `code_interpreter: object { input, outputs }` + The tool invocation context(s). - The Code Interpreter tool call definition. + - `"direct"` - - `input: string` + - `"programmatic"` - The input to the Code Interpreter tool call. + - `defer_loading: optional boolean` - - `outputs: array of object { logs, type } or object { image, type }` + Whether this tool should be deferred and discovered via tool search. - The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. + - `description: optional string` - - `CodeInterpreterLogOutput object { logs, type }` + Optional description of the custom tool, used to provide more context. - Text output from the Code Interpreter tool call as part of a run step. + - `format: optional object { type } or object { definition, syntax, type }` - - `logs: string` + The input format for the custom tool. Default is unconstrained text. - The text output from the Code Interpreter tool call. + - `Text object { type }` - - `type: "logs"` + Unconstrained free-form text. - Always `logs`. + - `type: "text"` - - `"logs"` + Unconstrained text format. Always `text`. - - `CodeInterpreterImageOutput object { image, type }` + - `"text"` - - `image: object { file_id }` + - `Grammar object { definition, syntax, type }` - - `file_id: string` + A grammar defined by the user. - The [file](/docs/api-reference/files) ID of the image. + - `definition: string` - - `type: "image"` + The grammar definition. - Always `image`. + - `syntax: "lark" or "regex"` - - `"image"` + The syntax of the grammar definition. One of `lark` or `regex`. - - `type: "code_interpreter"` + - `"lark"` - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + - `"regex"` - - `"code_interpreter"` + - `type: "grammar"` - - `FileSearchToolCall object { id, file_search, type }` + Grammar format. Always `grammar`. - - `id: string` + - `"grammar"` - The ID of the tool call object. + - `type: "namespace"` - - `file_search: object { ranking_options, results }` + The type of the tool. Always `namespace`. - For now, this is always going to be an empty object. + - `"namespace"` - - `ranking_options: optional object { ranker, score_threshold }` + - `ToolSearch object { type, description, execution, parameters }` - The ranking options for the file search. + Hosted or BYOT tool search configuration for deferred tools. - - `ranker: "auto" or "default_2024_08_21"` + - `type: "tool_search"` - The ranker to use for the file search. If not specified will use the `auto` ranker. + The type of the tool. Always `tool_search`. - - `"auto"` + - `"tool_search"` - - `"default_2024_08_21"` + - `description: optional string` - - `score_threshold: number` + Description shown to the model for a client-executed tool search tool. - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `execution: optional "server" or "client"` - - `results: optional array of object { file_id, file_name, score, content }` + Whether tool search is executed by the server or by the client. - The results of the file search. + - `"server"` - - `file_id: string` + - `"client"` - The ID of the file that result was found in. + - `parameters: optional unknown` - - `file_name: string` + Parameter schema for a client-executed tool search tool. - The name of the file that result was found in. + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - - `score: 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 score of the result. All values must be a floating point number between 0 and 1. + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - - `content: optional array of object { text, type }` + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - The content of the result that was found. The content is only included if requested via the include query parameter. + - `"web_search_preview"` - - `text: optional string` + - `"web_search_preview_2025_03_11"` - The text content of the file. + - `search_content_types: optional array of "text" or "image"` - - `type: optional "text"` + - `"text"` - The type of the content. + - `"image"` - - `"text"` + - `search_context_size: optional "low" or "medium" or "high"` - - `type: "file_search"` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - The type of tool call. This is always going to be `file_search` for this type of tool call. + - `"low"` - - `"file_search"` + - `"medium"` - - `FunctionToolCall object { id, function, type }` + - `"high"` - - `id: string` + - `user_location: optional object { type, city, country, 2 more }` - The ID of the tool call object. + The user's location. - - `function: object { arguments, name, output }` + - `type: "approximate"` - The definition of the function that was called. + The type of location approximation. Always `approximate`. - - `arguments: string` + - `"approximate"` - The arguments passed to the function. + - `city: optional string` - - `name: string` + Free text input for the city of the user, e.g. `San Francisco`. - The name of the function. + - `country: optional string` - - `output: string` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. + - `region: optional string` - - `type: "function"` + Free text input for the region of the user, e.g. `California`. - The type of tool call. This is always going to be `function` for this type of tool call. + - `timezone: optional string` - - `"function"` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `type: "tool_calls"` + - `ApplyPatch object { type, allowed_callers }` - Always `tool_calls`. + Allows the assistant to create, delete, or update files using unified diffs. - - `"tool_calls"` + - `type: "apply_patch"` - - `thread_id: string` + The type of the tool. Always `apply_patch`. - The ID of the [thread](/docs/api-reference/threads) that was run. + - `"apply_patch"` - - `type: "message_creation" or "tool_calls"` + - `allowed_callers: optional array of "direct" or "programmatic"` - The type of run step, which can be either `message_creation` or `tool_calls`. + The tool invocation context(s). - - `"message_creation"` + - `"direct"` - - `"tool_calls"` + - `"programmatic"` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `type: "additional_tools"` - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + The item type. Always `additional_tools`. - - `completion_tokens: number` + - `"additional_tools"` - Number of completion tokens used over the course of the run step. + - `id: optional string` - - `prompt_tokens: number` + The unique ID of this additional tools item. - Number of prompt tokens used over the course of the run step. + - `agent: optional object { agent_name }` - - `total_tokens: number` + The agent that produced this item. - Total number of tokens used (prompt + completion). + - `agent_name: string` - - `event: "thread.run.step.created"` + The canonical name of the agent that produced this item. - - `"thread.run.step.created"` + - `Reasoning object { id, summary, type, 4 more }` - - `object { data, event }` + 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). - Occurs when a [run step](/docs/api-reference/run-steps/step-object) moves to an `in_progress` state. + - `id: string` - - `data: RunStep` + The unique identifier of the reasoning content. - Represents a step in execution of a run. + - `summary: array of object { text, type }` - - `event: "thread.run.step.in_progress"` + Reasoning summary content. - - `"thread.run.step.in_progress"` + - `text: string` - - `object { data, event }` + A summary of the reasoning output from the model so far. - Occurs when parts of a [run step](/docs/api-reference/run-steps/step-object) are being streamed. + - `type: "summary_text"` - - `data: RunStepDeltaEvent` + The type of the object. Always `summary_text`. - Represents a run step delta i.e. any changed fields on a run step during streaming. + - `"summary_text"` - - `id: string` + - `type: "reasoning"` - The identifier of the run step, which can be referenced in API endpoints. + The type of the object. Always `reasoning`. - - `delta: object { step_details }` + - `"reasoning"` - The delta containing the fields that have changed on the run step. + - `agent: optional object { agent_name }` - - `step_details: optional RunStepDeltaMessageDelta or ToolCallDeltaObject` + The agent that produced this item. - The details of the run step. + - `agent_name: string` - - `RunStepDeltaMessageDelta object { type, message_creation }` + The canonical name of the agent that produced this item. - Details of the message creation by the run step. + - `content: optional array of object { text, type }` - - `type: "message_creation"` + Reasoning text content. - Always `message_creation`. + - `text: string` - - `"message_creation"` + The reasoning text from the model. - - `message_creation: optional object { message_id }` + - `type: "reasoning_text"` - - `message_id: optional string` + The type of the reasoning text. Always `reasoning_text`. - The ID of the message that was created by this run step. + - `"reasoning_text"` - - `ToolCallDeltaObject object { type, tool_calls }` + - `encrypted_content: optional string` - Details of the tool call. + 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: "tool_calls"` + - `status: optional "in_progress" or "completed" or "incomplete"` - Always `tool_calls`. + The status of the item. One of `in_progress`, `completed`, or + `incomplete`. Populated when items are returned via API. - - `"tool_calls"` + - `"in_progress"` - - `tool_calls: optional array of CodeInterpreterToolCallDelta or FileSearchToolCallDelta or FunctionToolCallDelta` + - `"completed"` - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + - `"incomplete"` - - `CodeInterpreterToolCallDelta object { index, type, id, code_interpreter }` + - `Compaction object { encrypted_content, type, id, agent }` - Details of the Code Interpreter tool call the run step was involved in. + A compaction item generated by the [`v1/responses/compact` API](/docs/api-reference/responses/compact). - - `index: number` + - `encrypted_content: string` - The index of the tool call in the tool calls array. + The encrypted content of the compaction summary. - - `type: "code_interpreter"` + - `type: "compaction"` - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + The type of the item. Always `compaction`. - - `"code_interpreter"` + - `"compaction"` - `id: optional string` - The ID of the tool call. - - - `code_interpreter: optional object { input, outputs }` + The ID of the compaction item. - The Code Interpreter tool call definition. + - `agent: optional object { agent_name }` - - `input: optional string` + The agent that produced this item. - The input to the Code Interpreter tool call. + - `agent_name: string` - - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` + The canonical name of the agent that produced this item. - The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. + - `ImageGenerationCall object { id, result, status, 2 more }` - - `CodeInterpreterLogs object { index, type, logs }` + An image generation request made by the model. - Text output from the Code Interpreter tool call as part of a run step. + - `id: string` - - `index: number` + The unique ID of the image generation call. - The index of the output in the outputs array. + - `result: string` - - `type: "logs"` + The generated image encoded in base64. - Always `logs`. + - `status: "in_progress" or "completed" or "generating" or "failed"` - - `"logs"` + The status of the image generation call. - - `logs: optional string` + - `"in_progress"` - The text output from the Code Interpreter tool call. + - `"completed"` - - `CodeInterpreterOutputImage object { index, type, image }` + - `"generating"` - - `index: number` + - `"failed"` - The index of the output in the outputs array. + - `type: "image_generation_call"` - - `type: "image"` + The type of the image generation call. Always `image_generation_call`. - Always `image`. + - `"image_generation_call"` - - `"image"` + - `agent: optional object { agent_name }` - - `image: optional object { file_id }` + The agent that produced this item. - - `file_id: optional string` + - `agent_name: string` - The [file](/docs/api-reference/files) ID of the image. + The canonical name of the agent that produced this item. - - `FileSearchToolCallDelta object { file_search, index, type, id }` + - `CodeInterpreterCall object { id, code, container_id, 4 more }` - - `file_search: unknown` + A tool call to run code. - For now, this is always going to be an empty object. + - `id: string` - - `index: number` + The unique ID of the code interpreter tool call. - The index of the tool call in the tool calls array. + - `code: string` - - `type: "file_search"` + The code to run, or null if not available. - The type of tool call. This is always going to be `file_search` for this type of tool call. + - `container_id: string` - - `"file_search"` + The ID of the container used to run the code. - - `id: optional string` + - `outputs: array of object { logs, type } or object { type, url }` - The ID of the tool call object. + The outputs generated by the code interpreter, such as logs or images. + Can be null if no outputs are available. - - `FunctionToolCallDelta object { index, type, id, function }` + - `Logs object { logs, type }` - - `index: number` + The logs output from the code interpreter. - The index of the tool call in the tool calls array. + - `logs: string` - - `type: "function"` + The logs output from the code interpreter. - The type of tool call. This is always going to be `function` for this type of tool call. + - `type: "logs"` - - `"function"` + The type of the output. Always `logs`. - - `id: optional string` + - `"logs"` - The ID of the tool call object. + - `Image object { type, url }` - - `function: optional object { arguments, name, output }` + The image output from the code interpreter. - The definition of the function that was called. + - `type: "image"` - - `arguments: optional string` + The type of the output. Always `image`. - The arguments passed to the function. + - `"image"` - - `name: optional string` + - `url: string` - The name of the function. + The URL of the image output from the code interpreter. - - `output: optional string` + - `status: "in_progress" or "completed" or "incomplete" or 2 more` - The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. + The status of the code interpreter tool call. Valid values are `in_progress`, `completed`, `incomplete`, `interpreting`, and `failed`. - - `object: "thread.run.step.delta"` + - `"in_progress"` - The object type, which is always `thread.run.step.delta`. + - `"completed"` - - `"thread.run.step.delta"` + - `"incomplete"` - - `event: "thread.run.step.delta"` + - `"interpreting"` - - `"thread.run.step.delta"` + - `"failed"` - - `object { data, event }` + - `type: "code_interpreter_call"` - Occurs when a [run step](/docs/api-reference/run-steps/step-object) is completed. + The type of the code interpreter tool call. Always `code_interpreter_call`. - - `data: RunStep` + - `"code_interpreter_call"` - Represents a step in execution of a run. + - `agent: optional object { agent_name }` - - `event: "thread.run.step.completed"` + The agent that produced this item. - - `"thread.run.step.completed"` + - `agent_name: string` - - `object { data, event }` + The canonical name of the agent that produced this item. - Occurs when a [run step](/docs/api-reference/run-steps/step-object) fails. + - `LocalShellCall object { id, action, call_id, 3 more }` - - `data: RunStep` + A tool call to run a command on the local shell. - Represents a step in execution of a run. + - `id: string` - - `event: "thread.run.step.failed"` + The unique ID of the local shell call. - - `"thread.run.step.failed"` + - `action: object { command, env, type, 3 more }` - - `object { data, event }` + Execute a shell command on the server. - Occurs when a [run step](/docs/api-reference/run-steps/step-object) is cancelled. + - `command: array of string` - - `data: RunStep` + The command to run. - Represents a step in execution of a run. + - `env: map[string]` - - `event: "thread.run.step.cancelled"` + Environment variables to set for the command. - - `"thread.run.step.cancelled"` + - `type: "exec"` - - `object { data, event }` + The type of the local shell action. Always `exec`. - Occurs when a [run step](/docs/api-reference/run-steps/step-object) expires. + - `"exec"` - - `data: RunStep` + - `timeout_ms: optional number` - Represents a step in execution of a run. + Optional timeout in milliseconds for the command. - - `event: "thread.run.step.expired"` + - `user: optional string` - - `"thread.run.step.expired"` + Optional user to run the command as. - - `object { data, event }` + - `working_directory: optional string` - Occurs when a [message](/docs/api-reference/messages/object) is created. + Optional working directory to run the command in. - - `data: Message` + - `call_id: string` - Represents a message within a [thread](/docs/api-reference/threads). + The unique ID of the local shell tool call generated by the model. - - `id: string` + - `status: "in_progress" or "completed" or "incomplete"` - The identifier, which can be referenced in API endpoints. + The status of the local shell call. - - `assistant_id: string` + - `"in_progress"` - If applicable, the ID of the [assistant](/docs/api-reference/assistants) that authored this message. + - `"completed"` - - `attachments: array of object { file_id, tools }` + - `"incomplete"` - A list of files attached to the message, and the tools they were added to. + - `type: "local_shell_call"` - - `file_id: optional string` + The type of the local shell call. Always `local_shell_call`. - The ID of the file to attach to the message. + - `"local_shell_call"` - - `tools: optional array of CodeInterpreterTool or object { type }` + - `agent: optional object { agent_name }` - The tools to add this file to. + The agent that produced this item. - - `CodeInterpreterTool object { type }` + - `agent_name: string` - - `FileSearchTool object { type }` + The canonical name of the agent that produced this item. - - `type: "file_search"` + - `LocalShellCallOutput object { id, output, type, 2 more }` - The type of tool being defined: `file_search` + The output of a local shell tool call. - - `"file_search"` + - `id: string` - - `completed_at: number` + The unique ID of the local shell tool call generated by the model. - The Unix timestamp (in seconds) for when the message was completed. + - `output: string` - - `content: array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlock or RefusalContentBlock` + A JSON string of the output of the local shell tool call. - The content of the message in array of text and/or images. + - `type: "local_shell_call_output"` - - `ImageFileContentBlock object { image_file, type }` + The type of the local shell tool call output. Always `local_shell_call_output`. - References an image [File](/docs/api-reference/files) in the content of a message. + - `"local_shell_call_output"` - - `image_file: ImageFile` + - `agent: optional object { agent_name }` - - `file_id: string` + The agent that produced this item. - The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + - `agent_name: string` - - `detail: optional "auto" or "low" or "high"` + The canonical name of the agent that produced this item. - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `"auto"` + The status of the item. One of `in_progress`, `completed`, or `incomplete`. - - `"low"` + - `"in_progress"` - - `"high"` + - `"completed"` - - `type: "image_file"` + - `"incomplete"` - Always `image_file`. + - `ShellCall object { action, call_id, type, 5 more }` - - `"image_file"` + A tool representing a request to execute one or more shell commands. - - `ImageURLContentBlock object { image_url, type }` + - `action: object { commands, max_output_length, timeout_ms }` - References an image URL in the content of a message. + The shell commands and limits that describe how to run the tool call. - - `image_url: ImageURL` + - `commands: array of string` - - `url: string` + Ordered shell commands for the execution environment to run. - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `max_output_length: optional number` - - `detail: optional "auto" or "low" or "high"` + Maximum number of UTF-8 characters to capture from combined stdout and stderr output. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `timeout_ms: optional number` - - `"auto"` + Maximum wall-clock time in milliseconds to allow the shell commands to run. - - `"low"` + - `call_id: string` - - `"high"` + The unique ID of the shell tool call generated by the model. - - `type: "image_url"` + - `type: "shell_call"` - The type of the content part. + The type of the item. Always `shell_call`. - - `"image_url"` + - `"shell_call"` - - `TextContentBlock object { text, type }` + - `id: optional string` - The text content that is part of a message. + The unique ID of the shell tool call. Populated when this item is returned via API. - - `text: Text` + - `agent: optional object { agent_name }` - - `annotations: array of FileCitationAnnotation or FilePathAnnotation` + The agent that produced this item. - - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` + - `agent_name: string` - A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + The canonical name of the agent that produced this item. - - `end_index: number` + - `caller: optional object { type } or object { caller_id, type }` - - `file_citation: object { file_id }` + The execution context that produced this tool call. - - `file_id: string` + - `Direct object { type }` - The ID of the specific File the citation is from. + - `type: "direct"` - - `start_index: number` + The caller type. Always `direct`. - - `text: string` + - `"direct"` - The text in the message content that needs to be replaced. + - `Program object { caller_id, type }` - - `type: "file_citation"` + - `caller_id: string` - Always `file_citation`. + The call ID of the program item that produced this tool call. - - `"file_citation"` + - `type: "program"` - - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` + The caller type. Always `program`. - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `"program"` - - `end_index: number` + - `environment: optional BetaLocalEnvironment or BetaContainerReference` - - `file_path: object { file_id }` + The environment to execute the shell commands in. - - `file_id: string` + - `BetaLocalEnvironment object { type, skills }` - The ID of the file that was generated. + - `BetaContainerReference object { container_id, type }` - - `start_index: number` + - `status: optional "in_progress" or "completed" or "incomplete"` - - `text: string` + The status of the shell call. One of `in_progress`, `completed`, or `incomplete`. - The text in the message content that needs to be replaced. + - `"in_progress"` - - `type: "file_path"` + - `"completed"` - Always `file_path`. + - `"incomplete"` - - `"file_path"` + - `ShellCallOutput object { call_id, output, type, 5 more }` - - `value: string` + The streamed output items emitted by a shell tool call. - The data that makes up the text. + - `call_id: string` - - `type: "text"` + The unique ID of the shell tool call generated by the model. - Always `text`. + - `output: array of BetaResponseFunctionShellCallOutputContent` - - `"text"` + Captured chunks of stdout and stderr output, along with their associated outcomes. - - `RefusalContentBlock object { refusal, type }` + - `outcome: object { type } or object { exit_code, type }` - The refusal content generated by the assistant. + The exit or timeout outcome associated with this shell call. - - `refusal: string` + - `Timeout object { type }` - - `type: "refusal"` + Indicates that the shell call exceeded its configured time limit. - Always `refusal`. + - `type: "timeout"` - - `"refusal"` + The outcome type. Always `timeout`. - - `created_at: number` + - `"timeout"` - The Unix timestamp (in seconds) for when the message was created. + - `Exit object { exit_code, type }` - - `incomplete_at: number` + Indicates that the shell commands finished and returned an exit code. - The Unix timestamp (in seconds) for when the message was marked as incomplete. + - `exit_code: number` - - `incomplete_details: object { reason }` + The exit code returned by the shell process. - On an incomplete message, details about why the message is incomplete. + - `type: "exit"` - - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` + The outcome type. Always `exit`. - The reason the message is incomplete. + - `"exit"` - - `"content_filter"` + - `stderr: string` - - `"max_tokens"` + Captured stderr output for the shell call. - - `"run_cancelled"` + - `stdout: string` - - `"run_expired"` + Captured stdout output for the shell call. - - `"run_failed"` + - `type: "shell_call_output"` - - `metadata: Metadata` + The type of the item. Always `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. + - `"shell_call_output"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `id: optional string` - - `object: "thread.message"` + The unique ID of the shell tool call output. Populated when this item is returned via API. - The object type, which is always `thread.message`. + - `agent: optional object { agent_name }` - - `"thread.message"` + The agent that produced this item. - - `role: "user" or "assistant"` + - `agent_name: string` - The entity that produced the message. One of `user` or `assistant`. + The canonical name of the agent that produced this item. - - `"user"` + - `caller: optional object { type } or object { caller_id, type }` - - `"assistant"` + The execution context that produced this tool call. - - `run_id: string` + - `Direct object { type }` - The ID of the [run](/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + - `type: "direct"` - - `status: "in_progress" or "incomplete" or "completed"` + The caller type. Always `direct`. - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `"direct"` - - `"in_progress"` + - `Program object { caller_id, type }` - - `"incomplete"` + - `caller_id: string` - - `"completed"` + The call ID of the program item that produced this tool call. - - `thread_id: string` + - `type: "program"` - The [thread](/docs/api-reference/threads) ID that this message belongs to. + The caller type. Always `program`. - - `event: "thread.message.created"` + - `"program"` - - `"thread.message.created"` + - `max_output_length: optional number` - - `object { data, event }` + The maximum number of UTF-8 characters captured for this shell call's combined output. - Occurs when a [message](/docs/api-reference/messages/object) moves to an `in_progress` state. + - `status: optional "in_progress" or "completed" or "incomplete"` - - `data: Message` + The status of the shell call output. - Represents a message within a [thread](/docs/api-reference/threads). + - `"in_progress"` - - `event: "thread.message.in_progress"` + - `"completed"` - - `"thread.message.in_progress"` + - `"incomplete"` - - `object { data, event }` + - `ApplyPatchCall object { call_id, operation, status, 4 more }` - Occurs when parts of a [Message](/docs/api-reference/messages/object) are being streamed. + A tool call representing a request to create, delete, or update files using diff patches. - - `data: MessageDeltaEvent` + - `call_id: string` - Represents a message delta i.e. any changed fields on a message during streaming. + The unique ID of the apply patch tool call generated by the model. - - `id: string` + - `operation: object { diff, path, type } or object { path, type } or object { diff, path, type }` - The identifier of the message, which can be referenced in API endpoints. + The specific create, delete, or update instruction for the apply_patch tool call. - - `delta: MessageDelta` + - `CreateFile object { diff, path, type }` - The delta containing the fields that have changed on the Message. + Instruction for creating a new file via the apply_patch tool. - - `content: optional array of ImageFileDeltaBlock or TextDeltaBlock or RefusalDeltaBlock or ImageURLDeltaBlock` + - `diff: string` - The content of the message in array of text and/or images. + Unified diff content to apply when creating the file. - - `ImageFileDeltaBlock object { index, type, image_file }` + - `path: string` - References an image [File](/docs/api-reference/files) in the content of a message. + Path of the file to create relative to the workspace root. - - `index: number` + - `type: "create_file"` - The index of the content part in the message. + The operation type. Always `create_file`. - - `type: "image_file"` + - `"create_file"` - Always `image_file`. + - `DeleteFile object { path, type }` - - `"image_file"` + Instruction for deleting an existing file via the apply_patch tool. - - `image_file: optional ImageFileDelta` + - `path: string` - - `detail: optional "auto" or "low" or "high"` + Path of the file to delete relative to the workspace root. - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `type: "delete_file"` - - `"auto"` + The operation type. Always `delete_file`. - - `"low"` + - `"delete_file"` - - `"high"` + - `UpdateFile object { diff, path, type }` - - `file_id: optional string` + Instruction for updating an existing file via the apply_patch tool. - The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + - `diff: string` - - `TextDeltaBlock object { index, type, text }` + Unified diff content to apply to the existing file. - The text content that is part of a message. + - `path: string` - - `index: number` + Path of the file to update relative to the workspace root. - The index of the content part in the message. + - `type: "update_file"` - - `type: "text"` + The operation type. Always `update_file`. - Always `text`. + - `"update_file"` - - `"text"` + - `status: "in_progress" or "completed"` - - `text: optional TextDelta` + The status of the apply patch tool call. One of `in_progress` or `completed`. - - `annotations: optional array of FileCitationDeltaAnnotation or FilePathDeltaAnnotation` + - `"in_progress"` - - `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` + - `"completed"` - A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + - `type: "apply_patch_call"` - - `index: number` + The type of the item. Always `apply_patch_call`. - The index of the annotation in the text content part. + - `"apply_patch_call"` - - `type: "file_citation"` + - `id: optional string` - Always `file_citation`. + The unique ID of the apply patch tool call. Populated when this item is returned via API. - - `"file_citation"` + - `agent: optional object { agent_name }` - - `end_index: optional number` + The agent that produced this item. - - `file_citation: optional object { file_id, quote }` + - `agent_name: string` - - `file_id: optional string` + The canonical name of the agent that produced this item. - The ID of the specific File the citation is from. + - `caller: optional object { type } or object { caller_id, type }` - - `quote: optional string` + The execution context that produced this tool call. - The specific quote in the file. + - `Direct object { type }` - - `start_index: optional number` + - `type: "direct"` - - `text: optional string` + The caller type. Always `direct`. - The text in the message content that needs to be replaced. + - `"direct"` - - `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` + - `Program object { caller_id, type }` - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `caller_id: string` - - `index: number` + The call ID of the program item that produced this tool call. - The index of the annotation in the text content part. + - `type: "program"` - - `type: "file_path"` + The caller type. Always `program`. - Always `file_path`. + - `"program"` - - `"file_path"` + - `ApplyPatchCallOutput object { call_id, status, type, 4 more }` - - `end_index: optional number` + The streamed output emitted by an apply patch tool call. - - `file_path: optional object { file_id }` + - `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 that was generated. + - `status: "completed" or "failed"` - - `start_index: optional number` + The status of the apply patch tool call output. One of `completed` or `failed`. - - `text: optional string` + - `"completed"` - The text in the message content that needs to be replaced. + - `"failed"` - - `value: optional string` + - `type: "apply_patch_call_output"` - The data that makes up the text. + The type of the item. Always `apply_patch_call_output`. - - `RefusalDeltaBlock object { index, type, refusal }` + - `"apply_patch_call_output"` - The refusal content that is part of a message. + - `id: optional string` - - `index: number` + The unique ID of the apply patch tool call output. Populated when this item is returned via API. - The index of the refusal part in the message. + - `agent: optional object { agent_name }` - - `type: "refusal"` + The agent that produced this item. - Always `refusal`. + - `agent_name: string` - - `"refusal"` + The canonical name of the agent that produced this item. - - `refusal: optional string` + - `caller: optional object { type } or object { caller_id, type }` - - `ImageURLDeltaBlock object { index, type, image_url }` + The execution context that produced this tool call. - References an image URL in the content of a message. + - `Direct object { type }` - - `index: number` + - `type: "direct"` - The index of the content part in the message. + The caller type. Always `direct`. - - `type: "image_url"` + - `"direct"` - Always `image_url`. + - `Program object { caller_id, type }` - - `"image_url"` + - `caller_id: string` - - `image_url: optional ImageURLDelta` + The call ID of the program item that produced this tool call. - - `detail: optional "auto" or "low" or "high"` + - `type: "program"` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. + The caller type. Always `program`. - - `"auto"` + - `"program"` - - `"low"` + - `output: optional string` - - `"high"` + Optional human-readable log text from the apply patch tool (e.g., patch results or errors). - - `url: optional string` + - `McpListTools object { id, server_label, tools, 3 more }` - The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + A list of tools available on an MCP server. - - `role: optional "user" or "assistant"` + - `id: string` - The entity that produced the message. One of `user` or `assistant`. + The unique ID of the list. - - `"user"` + - `server_label: string` - - `"assistant"` + The label of the MCP server. - - `object: "thread.message.delta"` + - `tools: array of object { input_schema, name, annotations, description }` - The object type, which is always `thread.message.delta`. + The tools available on the server. - - `"thread.message.delta"` + - `input_schema: unknown` - - `event: "thread.message.delta"` + The JSON schema describing the tool's input. - - `"thread.message.delta"` + - `name: string` - - `object { data, event }` + The name of the tool. - Occurs when a [message](/docs/api-reference/messages/object) is completed. + - `annotations: optional unknown` - - `data: Message` + Additional annotations about the tool. - Represents a message within a [thread](/docs/api-reference/threads). + - `description: optional string` - - `event: "thread.message.completed"` + The description of the tool. - - `"thread.message.completed"` + - `type: "mcp_list_tools"` - - `object { data, event }` + The type of the item. Always `mcp_list_tools`. - Occurs when a [message](/docs/api-reference/messages/object) ends before it is completed. + - `"mcp_list_tools"` - - `data: Message` + - `agent: optional object { agent_name }` - Represents a message within a [thread](/docs/api-reference/threads). + The agent that produced this item. - - `event: "thread.message.incomplete"` + - `agent_name: string` - - `"thread.message.incomplete"` + The canonical name of the agent that produced this item. - - `ErrorEvent object { data, event }` + - `error: optional string` - Occurs when an [error](/docs/guides/error-codes#api-errors) occurs. This can happen due to an internal server error or a timeout. + Error message if the server could not list tools. - - `data: ErrorObject` + - `McpApprovalRequest object { id, arguments, name, 3 more }` - - `code: string` + A request for human approval of a tool invocation. - - `message: string` + - `id: string` - - `param: string` + The unique ID of the approval request. - - `type: string` + - `arguments: string` - - `event: "error"` + A JSON string of arguments for the tool. - - `"error"` + - `name: string` - - `DoneEvent object { data, event }` + The name of the tool to run. - Occurs when a stream ends. + - `server_label: string` - - `data: "[DONE]"` + The label of the MCP server making the request. - - `"[DONE]"` + - `type: "mcp_approval_request"` - - `event: "done"` + The type of the item. Always `mcp_approval_request`. - - `"done"` + - `"mcp_approval_request"` -### Code Interpreter Tool + - `agent: optional object { agent_name }` -- `CodeInterpreterTool object { type }` + The agent that produced this item. - - `type: "code_interpreter"` + - `agent_name: string` - The type of tool being defined: `code_interpreter` + The canonical name of the agent that produced this item. - - `"code_interpreter"` + - `McpApprovalResponse object { approval_request_id, approve, type, 3 more }` -### File Search Tool + A response to an MCP approval request. -- `FileSearchTool object { type, file_search }` + - `approval_request_id: string` - - `type: "file_search"` + The ID of the approval request being answered. - The type of tool being defined: `file_search` + - `approve: boolean` - - `"file_search"` + Whether the request was approved. - - `file_search: optional object { max_num_results, ranking_options }` + - `type: "mcp_approval_response"` - Overrides for the file search tool. + The type of the item. Always `mcp_approval_response`. - - `max_num_results: optional number` + - `"mcp_approval_response"` - The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + - `id: optional string` - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + The unique ID of the approval response - - `ranking_options: optional object { score_threshold, ranker }` + - `agent: optional object { agent_name }` - The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + The agent that produced this item. - See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `agent_name: string` - - `score_threshold: number` + The canonical name of the agent that produced this item. - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `reason: optional string` - - `ranker: optional "auto" or "default_2024_08_21"` + Optional reason for the decision. - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `McpCall object { id, arguments, name, 7 more }` - - `"auto"` + An invocation of a tool on an MCP server. - - `"default_2024_08_21"` + - `id: string` -### Function Tool + The unique ID of the tool call. -- `FunctionTool object { function, type }` + - `arguments: string` - - `function: FunctionDefinition` + A JSON string of the arguments passed to the tool. - `name: string` - The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + The name of the tool that was run. - - `description: optional string` + - `server_label: string` - A description of what the function does, used by the model to choose when and how to call the function. + The label of the MCP server running the tool. - - `parameters: optional FunctionParameters` + - `type: "mcp_call"` - The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + The type of the item. Always `mcp_call`. - Omitting `parameters` defines a function with an empty parameter list. + - `"mcp_call"` - - `strict: optional boolean` + - `agent: optional object { agent_name }` - Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-calling). + The agent that produced this item. - - `type: "function"` + - `agent_name: string` - The type of tool being defined: `function` + The canonical name of the agent that produced this item. - - `"function"` + - `approval_request_id: optional string` -### Message Stream Event + 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. -- `MessageStreamEvent = object { data, event } or object { data, event } or object { data, event } or 2 more` + - `error: optional string` - Occurs when a [message](/docs/api-reference/messages/object) is created. + The error from the tool call, if any. - - `object { data, event }` + - `output: optional string` - Occurs when a [message](/docs/api-reference/messages/object) is created. + The output from the tool call. - - `data: Message` + - `status: optional "in_progress" or "completed" or "incomplete" or 2 more` - Represents a message within a [thread](/docs/api-reference/threads). + The status of the tool call. One of `in_progress`, `completed`, `incomplete`, `calling`, or `failed`. - - `id: string` + - `"in_progress"` - The identifier, which can be referenced in API endpoints. + - `"completed"` - - `assistant_id: string` + - `"incomplete"` - If applicable, the ID of the [assistant](/docs/api-reference/assistants) that authored this message. + - `"calling"` - - `attachments: array of object { file_id, tools }` + - `"failed"` - A list of files attached to the message, and the tools they were added to. + - `CustomToolCallOutput object { call_id, output, type, 3 more }` - - `file_id: optional string` + The output of a custom tool call from your code, being sent back to the model. - The ID of the file to attach to the message. + - `call_id: string` - - `tools: optional array of CodeInterpreterTool or object { type }` + The call ID, used to map this custom tool call output to a custom tool call. - The tools to add this file to. + - `output: string or array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `CodeInterpreterTool object { type }` + The output from the custom tool call generated by your code. + Can be a string or an list of output content. - - `type: "code_interpreter"` + - `StringOutput = string` - The type of tool being defined: `code_interpreter` + A string of the output of the custom tool call. - - `"code_interpreter"` + - `OutputContentList = array of BetaResponseInputText or BetaResponseInputImage or BetaResponseInputFile` - - `FileSearchTool object { type }` + Text, image, or file output of the custom tool call. - - `type: "file_search"` + - `BetaResponseInputText object { text, type, prompt_cache_breakpoint }` - The type of tool being defined: `file_search` + A text input to the model. - - `"file_search"` + - `BetaResponseInputImage object { detail, type, file_id, 2 more }` - - `completed_at: number` + An image input to the model. Learn about [image inputs](/docs/guides/vision). - The Unix timestamp (in seconds) for when the message was completed. + - `BetaResponseInputFile object { type, detail, file_data, 4 more }` - - `content: array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlock or RefusalContentBlock` + A file input to the model. - The content of the message in array of text and/or images. + - `type: "custom_tool_call_output"` - - `ImageFileContentBlock object { image_file, type }` + The type of the custom tool call output. Always `custom_tool_call_output`. - References an image [File](/docs/api-reference/files) in the content of a message. + - `"custom_tool_call_output"` - - `image_file: ImageFile` + - `id: optional string` - - `file_id: string` + The unique ID of the custom tool call output in the OpenAI platform. - The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + - `agent: optional object { agent_name }` - - `detail: optional "auto" or "low" or "high"` + The agent that produced this item. - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `agent_name: string` - - `"auto"` + The canonical name of the agent that produced this item. - - `"low"` + - `caller: optional object { type } or object { caller_id, type }` - - `"high"` + The execution context that produced this tool call. - - `type: "image_file"` + - `Direct object { type }` - Always `image_file`. + - `type: "direct"` - - `"image_file"` + The caller type. Always `direct`. - - `ImageURLContentBlock object { image_url, type }` + - `"direct"` - References an image URL in the content of a message. + - `Program object { caller_id, type }` - - `image_url: ImageURL` + - `caller_id: string` - - `url: string` + The call ID of the program item that produced this tool call. - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `type: "program"` - - `detail: optional "auto" or "low" or "high"` + The caller type. Always `program`. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `"program"` - - `"auto"` + - `CustomToolCall object { call_id, input, name, 5 more }` - - `"low"` + A call to a custom tool created by the model. - - `"high"` + - `call_id: string` - - `type: "image_url"` + An identifier used to map this custom tool call to a tool call output. - The type of the content part. + - `input: string` - - `"image_url"` + The input for the custom tool call generated by the model. - - `TextContentBlock object { text, type }` + - `name: string` - The text content that is part of a message. + The name of the custom tool being called. - - `text: Text` + - `type: "custom_tool_call"` - - `annotations: array of FileCitationAnnotation or FilePathAnnotation` + The type of the custom tool call. Always `custom_tool_call`. - - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` + - `"custom_tool_call"` - A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + - `id: optional string` - - `end_index: number` + The unique ID of the custom tool call in the OpenAI platform. - - `file_citation: object { file_id }` + - `agent: optional object { agent_name }` - - `file_id: string` + The agent that produced this item. - The ID of the specific File the citation is from. + - `agent_name: string` - - `start_index: number` + The canonical name of the agent that produced this item. - - `text: string` + - `caller: optional object { type } or object { caller_id, type }` - The text in the message content that needs to be replaced. + The execution context that produced this tool call. - - `type: "file_citation"` + - `Direct object { type }` - Always `file_citation`. + - `type: "direct"` - - `"file_citation"` + - `"direct"` - - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` + - `Program object { caller_id, type }` - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `caller_id: string` - - `end_index: number` + The call ID of the program item that produced this tool call. - - `file_path: object { file_id }` + - `type: "program"` - - `file_id: string` + - `"program"` - The ID of the file that was generated. + - `namespace: optional string` - - `start_index: number` + The namespace of the custom tool being called. - - `text: string` + - `CompactionTrigger object { type, agent }` - The text in the message content that needs to be replaced. + Compacts the current context. Must be the final input item. - - `type: "file_path"` + - `type: "compaction_trigger"` - Always `file_path`. + The type of the item. Always `compaction_trigger`. - - `"file_path"` + - `"compaction_trigger"` - - `value: string` + - `agent: optional object { agent_name }` - The data that makes up the text. + The agent that produced this item. - - `type: "text"` + - `agent_name: string` - Always `text`. + The canonical name of the agent that produced this item. - - `"text"` + - `ItemReference object { id, agent, type }` - - `RefusalContentBlock object { refusal, type }` + An internal identifier for an item to reference. - The refusal content generated by the assistant. + - `id: string` - - `refusal: string` + The ID of the item to reference. - - `type: "refusal"` + - `agent: optional object { agent_name }` - Always `refusal`. + The agent that produced this item. - - `"refusal"` + - `agent_name: string` - - `created_at: number` + The canonical name of the agent that produced this item. - The Unix timestamp (in seconds) for when the message was created. + - `type: optional "item_reference"` - - `incomplete_at: number` + The type of item to reference. Always `item_reference`. - The Unix timestamp (in seconds) for when the message was marked as incomplete. + - `"item_reference"` - - `incomplete_details: object { reason }` + - `Program object { id, call_id, code, 3 more }` - On an incomplete message, details about why the message is incomplete. + - `id: string` - - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` + The unique ID of this program item. - The reason the message is incomplete. + - `call_id: string` - - `"content_filter"` + The stable call ID of the program item. - - `"max_tokens"` + - `code: string` - - `"run_cancelled"` + The JavaScript source executed by programmatic tool calling. - - `"run_expired"` + - `fingerprint: string` - - `"run_failed"` + Opaque program replay fingerprint that must be round-tripped. - - `metadata: Metadata` + - `type: "program"` - 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 item type. Always `program`. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"program"` - - `object: "thread.message"` + - `agent: optional object { agent_name }` - The object type, which is always `thread.message`. + The agent that produced this item. - - `"thread.message"` + - `agent_name: string` - - `role: "user" or "assistant"` + The canonical name of the agent that produced this item. - The entity that produced the message. One of `user` or `assistant`. + - `ProgramOutput object { id, call_id, result, 3 more }` - - `"user"` + - `id: string` - - `"assistant"` + The unique ID of this program output item. - - `run_id: string` + - `call_id: string` - The ID of the [run](/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + The call ID of the program item. - - `status: "in_progress" or "incomplete" or "completed"` + - `result: string` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + The result produced by the program item. - - `"in_progress"` + - `status: "completed" or "incomplete"` - - `"incomplete"` + The terminal status of the program output. - `"completed"` - - `thread_id: string` + - `"incomplete"` - The [thread](/docs/api-reference/threads) ID that this message belongs to. + - `type: "program_output"` - - `event: "thread.message.created"` + The item type. Always `program_output`. - - `"thread.message.created"` + - `"program_output"` - - `object { data, event }` + - `agent: optional object { agent_name }` - Occurs when a [message](/docs/api-reference/messages/object) moves to an `in_progress` state. + The agent that produced this item. - - `data: Message` + - `agent_name: string` - Represents a message within a [thread](/docs/api-reference/threads). + The canonical name of the agent that produced this item. - - `event: "thread.message.in_progress"` +- `instructions: optional string` - - `"thread.message.in_progress"` + 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. - - `object { data, event }` +- `model: optional string` - Occurs when parts of a [Message](/docs/api-reference/messages/object) are being streamed. + 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. - - `data: MessageDeltaEvent` +- `parallel_tool_calls: optional boolean` - Represents a message delta i.e. any changed fields on a message during streaming. + Whether to allow the model to run tool calls in parallel. - - `id: string` +- `personality: optional string or "friendly" or "pragmatic"` - The identifier of the message, which can be referenced in API endpoints. + A model-owned style preset to apply to this request. Omit this parameter to use the model's default style. Supported values may expand over time. Values must be at most 64 characters. - - `delta: MessageDelta` + - `string` - The delta containing the fields that have changed on the Message. + - `"friendly" or "pragmatic"` - - `content: optional array of ImageFileDeltaBlock or TextDeltaBlock or RefusalDeltaBlock or ImageURLDeltaBlock` + A model-owned style preset to apply to this request. Omit this parameter to use the model's default style. Supported values may expand over time. Values must be at most 64 characters. - The content of the message in array of text and/or images. + - `"friendly"` - - `ImageFileDeltaBlock object { index, type, image_file }` + - `"pragmatic"` - References an image [File](/docs/api-reference/files) in the content of a message. +- `previous_response_id: optional string` - - `index: number` + 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 index of the content part in the message. +- `reasoning: optional object { context, effort, generate_summary, 2 more }` - - `type: "image_file"` + **gpt-5 and o-series models only** Configuration options for [reasoning models](https://platform.openai.com/docs/guides/reasoning). - Always `image_file`. + - `context: optional "auto" or "current_turn" or "all_turns"` - - `"image_file"` + 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`. - - `image_file: optional ImageFileDelta` + When returned on a response, this is the effective reasoning context mode + used for the response. - - `detail: optional "auto" or "low" or "high"` + - `"auto"` - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `"current_turn"` - - `"auto"` + - `"all_turns"` - - `"low"` + - `effort: optional "none" or "minimal" or "low" or 4 more` - - `"high"` + 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. - - `file_id: optional string` + - `"none"` - The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + - `"minimal"` - - `TextDeltaBlock object { index, type, text }` + - `"low"` - The text content that is part of a message. + - `"medium"` - - `index: number` + - `"high"` - The index of the content part in the message. + - `"xhigh"` - - `type: "text"` + - `"max"` - Always `text`. + - `generate_summary: optional "auto" or "concise" or "detailed"` - - `"text"` + **Deprecated:** use `summary` instead. - - `text: optional TextDelta` + 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 array of FileCitationDeltaAnnotation or FilePathDeltaAnnotation` + - `"auto"` - - `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` + - `"concise"` - A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + - `"detailed"` - - `index: number` + - `mode: optional string or "standard" or "pro"` - The index of the annotation in the text content part. + Controls the reasoning execution mode for the request. - - `type: "file_citation"` + When returned on a response, this is the effective execution mode. - Always `file_citation`. + - `string` - - `"file_citation"` + - `"standard" or "pro"` - - `end_index: optional number` + Controls the reasoning execution mode for the request. - - `file_citation: optional object { file_id, quote }` + When returned on a response, this is the effective execution mode. - - `file_id: optional string` + - `"standard"` - The ID of the specific File the citation is from. + - `"pro"` - - `quote: optional string` + - `summary: optional "auto" or "concise" or "detailed"` - The specific quote in the file. + 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`. - - `start_index: optional number` + `concise` is supported for `computer-use-preview` models and all reasoning models after `gpt-5`. - - `text: optional string` + - `"auto"` - The text in the message content that needs to be replaced. + - `"concise"` - - `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` + - `"detailed"` - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. +- `text: optional object { format, verbosity }` - - `index: number` + Configuration options for a text response from the model. Can be plain + text or structured JSON data. Learn more: - The index of the annotation in the text content part. + - [Text inputs and outputs](/docs/guides/text) + - [Structured Outputs](/docs/guides/structured-outputs) - - `type: "file_path"` + - `format: optional BetaResponseFormatTextConfig` - Always `file_path`. + An object specifying the format that the model must output. - - `"file_path"` + 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). - - `end_index: optional number` + The default format is `{ "type": "text" }` with no additional options. - - `file_path: optional object { file_id }` + **Not recommended for gpt-4o and newer models:** - - `file_id: 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. - The ID of the file that was generated. + - `Text object { type }` - - `start_index: optional number` + Default response format. Used to generate text responses. - - `text: optional string` + - `type: "text"` - The text in the message content that needs to be replaced. + The type of response format being defined. Always `text`. - - `value: optional string` + - `"text"` - The data that makes up the text. + - `BetaResponseFormatTextJSONSchemaConfig object { name, schema, type, 2 more }` - - `RefusalDeltaBlock object { index, type, refusal }` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - The refusal content that is part of a message. + - `name: string` - - `index: number` + 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 index of the refusal part in the message. + - `schema: map[unknown]` - - `type: "refusal"` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - Always `refusal`. + - `type: "json_schema"` - - `"refusal"` + The type of response format being defined. Always `json_schema`. - - `refusal: optional string` + - `"json_schema"` - - `ImageURLDeltaBlock object { index, type, image_url }` + - `description: optional string` - References an image URL in the content of a message. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `index: number` + - `strict: optional boolean` - The index of the content part 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: "image_url"` + - `JSONObject object { type }` - Always `image_url`. + 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. - - `"image_url"` + - `type: "json_object"` - - `image_url: optional ImageURLDelta` + The type of response format being defined. Always `json_object`. - - `detail: optional "auto" or "low" or "high"` + - `"json_object"` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `verbosity: optional "low" or "medium" or "high"` - - `"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`. - `"low"` + - `"medium"` + - `"high"` - - `url: optional string` +- `tool_choice: optional BetaToolChoiceOptions or BetaToolChoiceAllowed or BetaToolChoiceTypes or 6 more` - The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + Controls which tool the model should use, if any. - - `role: optional "user" or "assistant"` + - `BetaToolChoiceOptions = "none" or "auto" or "required"` - The entity that produced the message. One of `user` or `assistant`. + Controls which (if any) tool is called by the model. - - `"user"` + `none` means the model will not call any tool and instead generates a message. - - `"assistant"` + `auto` means the model can pick between generating a message or calling one or + more tools. - - `object: "thread.message.delta"` + `required` means the model must call one or more tools. - The object type, which is always `thread.message.delta`. + - `"none"` - - `"thread.message.delta"` + - `"auto"` - - `event: "thread.message.delta"` + - `"required"` - - `"thread.message.delta"` + - `BetaToolChoiceAllowed object { mode, tools, type }` - - `object { data, event }` + Constrains the tools available to the model to a pre-defined set. - Occurs when a [message](/docs/api-reference/messages/object) is completed. + - `mode: "auto" or "required"` - - `data: Message` + Constrains the tools available to the model to a pre-defined set. - Represents a message within a [thread](/docs/api-reference/threads). + `auto` allows the model to pick from among the allowed tools and generate a + message. - - `event: "thread.message.completed"` + `required` requires the model to call one or more of the allowed tools. - - `"thread.message.completed"` + - `"auto"` - - `object { data, event }` + - `"required"` - Occurs when a [message](/docs/api-reference/messages/object) ends before it is completed. + - `tools: array of map[unknown]` - - `data: Message` + A list of tool definitions that the model should be allowed to call. - Represents a message within a [thread](/docs/api-reference/threads). + For the Responses API, the list of tool definitions might look like: - - `event: "thread.message.incomplete"` + ```json + [ + { "type": "function", "name": "get_weather" }, + { "type": "mcp", "server_label": "deepwiki" }, + { "type": "image_generation" } + ] + ``` - - `"thread.message.incomplete"` + - `type: "allowed_tools"` -### Run Step Stream Event + Allowed tool configuration type. Always `allowed_tools`. -- `RunStepStreamEvent = object { data, event } or object { data, event } or object { data, event } or 4 more` + - `"allowed_tools"` - Occurs when a [run step](/docs/api-reference/run-steps/step-object) is created. + - `BetaToolChoiceTypes object { type }` - - `object { data, event }` + Indicates that the model should use a built-in tool to generate a response. + [Learn more about built-in tools](/docs/guides/tools). - Occurs when a [run step](/docs/api-reference/run-steps/step-object) is created. + - `type: "file_search" or "web_search_preview" or "computer" or 5 more` - - `data: RunStep` + The type of hosted tool the model should to use. Learn more about + [built-in tools](/docs/guides/tools). - Represents a step in execution of a run. + Allowed values are: - - `id: string` + - `file_search` + - `web_search_preview` + - `computer` + - `computer_use_preview` + - `computer_use` + - `code_interpreter` + - `image_generation` - The identifier of the run step, which can be referenced in API endpoints. + - `"file_search"` - - `assistant_id: string` + - `"web_search_preview"` - The ID of the [assistant](/docs/api-reference/assistants) associated with the run step. + - `"computer"` - - `cancelled_at: number` + - `"computer_use_preview"` - The Unix timestamp (in seconds) for when the run step was cancelled. + - `"computer_use"` - - `completed_at: number` + - `"web_search_preview_2025_03_11"` - The Unix timestamp (in seconds) for when the run step completed. + - `"image_generation"` - - `created_at: number` + - `"code_interpreter"` - The Unix timestamp (in seconds) for when the run step was created. + - `BetaToolChoiceFunction object { name, type }` - - `expired_at: number` + Use this option to force the model to call a specific function. - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + - `name: string` - - `failed_at: number` + The name of the function to call. - The Unix timestamp (in seconds) for when the run step failed. + - `type: "function"` - - `last_error: object { code, message }` + For function calling, the type is always `function`. - The last error associated with this run step. Will be `null` if there are no errors. + - `"function"` - - `code: "server_error" or "rate_limit_exceeded"` + - `BetaToolChoiceMcp object { server_label, type, name }` - One of `server_error` or `rate_limit_exceeded`. + Use this option to force the model to call a specific tool on a remote MCP server. - - `"server_error"` + - `server_label: string` - - `"rate_limit_exceeded"` + The label of the MCP server to use. - - `message: string` + - `type: "mcp"` - A human-readable description of the error. + For MCP tools, the type is always `mcp`. - - `metadata: Metadata` + - `"mcp"` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `name: optional string` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The name of the tool to call on the server. - - `object: "thread.run.step"` + - `BetaToolChoiceCustom object { name, type }` - The object type, which is always `thread.run.step`. + Use this option to force the model to call a specific custom tool. - - `"thread.run.step"` + - `name: string` - - `run_id: string` + The name of the custom tool to call. - The ID of the [run](/docs/api-reference/runs) that this run step is a part of. + - `type: "custom"` - - `status: "in_progress" or "cancelled" or "failed" or 2 more` + For custom tool calling, the type is always `custom`. - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + - `"custom"` - - `"in_progress"` + - `BetaSpecificProgrammaticToolCallingParam object { type }` - - `"cancelled"` + - `type: "programmatic_tool_calling"` - - `"failed"` + The tool to call. Always `programmatic_tool_calling`. - - `"completed"` + - `"programmatic_tool_calling"` - - `"expired"` + - `BetaToolChoiceApplyPatch object { type }` - - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` + Forces the model to call the apply_patch tool when executing a tool call. - The details of the run step. + - `type: "apply_patch"` - - `MessageCreationStepDetails object { message_creation, type }` + The tool to call. Always `apply_patch`. - Details of the message creation by the run step. + - `"apply_patch"` - - `message_creation: object { message_id }` + - `BetaToolChoiceShell object { type }` - - `message_id: string` + Forces the model to call the shell tool when a tool call is required. - The ID of the message that was created by this run step. + - `type: "shell"` - - `type: "message_creation"` + The tool to call. Always `shell`. - Always `message_creation`. + - `"shell"` - - `"message_creation"` +- `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` - - `ToolCallsStepDetails object { tool_calls, type }` + 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. - Details of the tool call. + - `Function object { name, parameters, strict, 5 more }` - - `tool_calls: array of CodeInterpreterToolCall or FileSearchToolCall or FunctionToolCall` + 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). - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + - `name: string` - - `CodeInterpreterToolCall object { id, code_interpreter, type }` + The name of the function to call. - Details of the Code Interpreter tool call the run step was involved in. + - `parameters: map[unknown]` - - `id: string` + A JSON schema object describing the parameters of the function. - The ID of the tool call. + - `strict: boolean` - - `code_interpreter: object { input, outputs }` + Whether strict parameter validation is enforced for this function tool. - The Code Interpreter tool call definition. + - `type: "function"` - - `input: string` + The type of the function tool. Always `function`. - The input to the Code Interpreter tool call. + - `"function"` - - `outputs: array of object { logs, type } or object { image, type }` + - `allowed_callers: optional array of "direct" or "programmatic"` - The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. + The tool invocation context(s). - - `CodeInterpreterLogOutput object { logs, type }` + - `"direct"` - Text output from the Code Interpreter tool call as part of a run step. + - `"programmatic"` + + - `defer_loading: optional boolean` + + Whether this function is deferred and loaded via tool search. - - `logs: string` + - `description: optional string` - The text output from the Code Interpreter tool call. + A description of the function. Used by the model to determine whether or not to call the function. - - `type: "logs"` + - `output_schema: optional map[unknown]` - Always `logs`. + A JSON schema object describing the JSON value encoded in string outputs for this function. - - `"logs"` + - `FileSearch object { type, vector_store_ids, filters, 2 more }` - - `CodeInterpreterImageOutput object { image, 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). - - `image: object { file_id }` + - `type: "file_search"` - - `file_id: string` + The type of the file search tool. Always `file_search`. - The [file](/docs/api-reference/files) ID of the image. + - `"file_search"` - - `type: "image"` + - `vector_store_ids: array of string` - Always `image`. + The IDs of the vector stores to search. - - `"image"` + - `filters: optional object { key, type, value } or object { filters, type }` - - `type: "code_interpreter"` + A filter to apply. - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + - `ComparisonFilter object { key, type, value }` - - `"code_interpreter"` + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `FileSearchToolCall object { id, file_search, type }` + - `key: string` - - `id: string` + The key to compare against the value. - The ID of the tool call object. + - `type: "eq" or "ne" or "gt" or 5 more` - - `file_search: object { ranking_options, results }` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - For now, this is always going to be an empty object. + - `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 - - `ranking_options: optional object { ranker, score_threshold }` + - `"eq"` - The ranking options for the file search. + - `"ne"` - - `ranker: "auto" or "default_2024_08_21"` + - `"gt"` - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `"gte"` - - `"auto"` + - `"lt"` - - `"default_2024_08_21"` + - `"lte"` - - `score_threshold: number` + - `"in"` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `"nin"` - - `results: optional array of object { file_id, file_name, score, content }` + - `value: string or number or boolean or array of string or number` - The results of the file search. + The value to compare against the attribute key; supports string, number, or boolean types. - - `file_id: string` + - `string` - The ID of the file that result was found in. + - `number` - - `file_name: string` + - `boolean` - The name of the file that result was found in. + - `array of string or number` - - `score: number` + - `string` - The score of the result. All values must be a floating point number between 0 and 1. + - `number` - - `content: optional array of object { text, type }` + - `CompoundFilter object { filters, type }` - The content of the result that was found. The content is only included if requested via the include query parameter. + Combine multiple filters using `and` or `or`. - - `text: optional string` + - `filters: array of object { key, type, value } or unknown` - The text content of the file. + Array of filters to combine. Items can be `ComparisonFilter` or `CompoundFilter`. - - `type: optional "text"` + - `ComparisonFilter object { key, type, value }` - The type of the content. + A filter used to compare a specified attribute key to a given value using a defined comparison operation. - - `"text"` + - `key: string` - - `type: "file_search"` + The key to compare against the value. - The type of tool call. This is always going to be `file_search` for this type of tool call. + - `type: "eq" or "ne" or "gt" or 5 more` - - `"file_search"` + Specifies the comparison operator: `eq`, `ne`, `gt`, `gte`, `lt`, `lte`, `in`, `nin`. - - `FunctionToolCall object { id, function, type }` + - `eq`: equals + - `ne`: not equal + - `gt`: greater than + - `gte`: greater than or equal + - `lt`: less than + - `lte`: less than or equal + - `in`: in + - `nin`: not in - - `id: string` + - `"eq"` - The ID of the tool call object. + - `"ne"` - - `function: object { arguments, name, output }` + - `"gt"` - The definition of the function that was called. + - `"gte"` - - `arguments: string` + - `"lt"` - The arguments passed to the function. + - `"lte"` - - `name: string` + - `"in"` - The name of the function. + - `"nin"` - - `output: string` + - `value: string or number or boolean or array of string or number` - The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. + The value to compare against the attribute key; supports string, number, or boolean types. - - `type: "function"` + - `string` - The type of tool call. This is always going to be `function` for this type of tool call. + - `number` - - `"function"` + - `boolean` - - `type: "tool_calls"` + - `array of string or number` - Always `tool_calls`. + - `string` - - `"tool_calls"` + - `number` - - `thread_id: string` + - `unknown` - The ID of the [thread](/docs/api-reference/threads) that was run. + - `type: "and" or "or"` - - `type: "message_creation" or "tool_calls"` + Type of operation: `and` or `or`. - The type of run step, which can be either `message_creation` or `tool_calls`. + - `"and"` - - `"message_creation"` + - `"or"` - - `"tool_calls"` + - `max_num_results: optional number` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + The maximum number of results to return. This number should be between 1 and 50 inclusive. - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + - `ranking_options: optional object { hybrid_search, ranker, score_threshold }` - - `completion_tokens: number` + Ranking options for search. - Number of completion tokens used over the course of the run step. + - `hybrid_search: optional object { embedding_weight, text_weight }` - - `prompt_tokens: number` + Weights that control how reciprocal rank fusion balances semantic embedding matches versus sparse keyword matches when hybrid search is enabled. - Number of prompt tokens used over the course of the run step. + - `embedding_weight: number` - - `total_tokens: number` + The weight of the embedding in the reciprocal ranking fusion. - Total number of tokens used (prompt + completion). + - `text_weight: number` - - `event: "thread.run.step.created"` + The weight of the text in the reciprocal ranking fusion. - - `"thread.run.step.created"` + - `ranker: optional "auto" or "default-2024-11-15"` - - `object { data, event }` + The ranker to use for the file search. - Occurs when a [run step](/docs/api-reference/run-steps/step-object) moves to an `in_progress` state. + - `"auto"` - - `data: RunStep` + - `"default-2024-11-15"` - Represents a step in execution of a run. + - `score_threshold: optional number` - - `event: "thread.run.step.in_progress"` + 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. - - `"thread.run.step.in_progress"` + - `Computer object { type }` - - `object { data, event }` + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - Occurs when parts of a [run step](/docs/api-reference/run-steps/step-object) are being streamed. + - `type: "computer"` - - `data: RunStepDeltaEvent` + The type of the computer tool. Always `computer`. - Represents a run step delta i.e. any changed fields on a run step during streaming. + - `"computer"` - - `id: string` + - `ComputerUsePreview object { display_height, display_width, environment, type }` - The identifier of the run step, which can be referenced in API endpoints. + A tool that controls a virtual computer. Learn more about the [computer tool](https://platform.openai.com/docs/guides/tools-computer-use). - - `delta: object { step_details }` + - `display_height: number` - The delta containing the fields that have changed on the run step. + The height of the computer display. - - `step_details: optional RunStepDeltaMessageDelta or ToolCallDeltaObject` + - `display_width: number` - The details of the run step. + The width of the computer display. - - `RunStepDeltaMessageDelta object { type, message_creation }` + - `environment: "windows" or "mac" or "linux" or 2 more` - Details of the message creation by the run step. + The type of computer environment to control. - - `type: "message_creation"` + - `"windows"` - Always `message_creation`. + - `"mac"` - - `"message_creation"` + - `"linux"` - - `message_creation: optional object { message_id }` + - `"ubuntu"` - - `message_id: optional string` + - `"browser"` - The ID of the message that was created by this run step. + - `type: "computer_use_preview"` - - `ToolCallDeltaObject object { type, tool_calls }` + The type of the computer use tool. Always `computer_use_preview`. - Details of the tool call. + - `"computer_use_preview"` - - `type: "tool_calls"` + - `WebSearch object { type, filters, search_context_size, user_location }` - Always `tool_calls`. + Search the Internet for sources related to the prompt. Learn more about the + [web search tool](/docs/guides/tools-web-search). - - `"tool_calls"` + - `type: "web_search" or "web_search_2025_08_26"` - - `tool_calls: optional array of CodeInterpreterToolCallDelta or FileSearchToolCallDelta or FunctionToolCallDelta` + The type of the web search tool. One of `web_search` or `web_search_2025_08_26`. - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + - `"web_search"` - - `CodeInterpreterToolCallDelta object { index, type, id, code_interpreter }` + - `"web_search_2025_08_26"` - Details of the Code Interpreter tool call the run step was involved in. + - `filters: optional object { allowed_domains }` - - `index: number` + Filters for the search. - The index of the tool call in the tool calls array. + - `allowed_domains: optional array of string` - - `type: "code_interpreter"` + Allowed domains for the search. If not provided, all domains are allowed. + Subdomains of the provided domains are allowed as well. - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + Example: `["pubmed.ncbi.nlm.nih.gov"]` - - `"code_interpreter"` + - `search_context_size: optional "low" or "medium" or "high"` - - `id: optional string` + High level guidance for the amount of context window space to use for the search. One of `low`, `medium`, or `high`. `medium` is the default. - The ID of the tool call. + - `"low"` - - `code_interpreter: optional object { input, outputs }` + - `"medium"` - The Code Interpreter tool call definition. + - `"high"` - - `input: optional string` + - `user_location: optional object { city, country, region, 2 more }` - The input to the Code Interpreter tool call. + The approximate location of the user. - - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` + - `city: optional string` - The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. + Free text input for the city of the user, e.g. `San Francisco`. - - `CodeInterpreterLogs object { index, type, logs }` + - `country: optional string` - Text output from the Code Interpreter tool call as part of a run step. + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `index: number` + - `region: optional string` - The index of the output in the outputs array. + Free text input for the region of the user, e.g. `California`. - - `type: "logs"` + - `timezone: optional string` - Always `logs`. + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - - `"logs"` + - `type: optional "approximate"` - - `logs: optional string` + The type of location approximation. Always `approximate`. - The text output from the Code Interpreter tool call. + - `"approximate"` - - `CodeInterpreterOutputImage object { index, type, image }` + - `Mcp object { server_label, type, allowed_callers, 9 more }` - - `index: number` + Give the model access to additional tools via remote Model Context Protocol + (MCP) servers. [Learn more about MCP](/docs/guides/tools-remote-mcp). - The index of the output in the outputs array. + - `server_label: string` - - `type: "image"` + A label for this MCP server, used to identify it in tool calls. - Always `image`. + - `type: "mcp"` - - `"image"` + The type of the MCP tool. Always `mcp`. - - `image: optional object { file_id }` + - `"mcp"` - - `file_id: optional string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The [file](/docs/api-reference/files) ID of the image. + The tool invocation context(s). - - `FileSearchToolCallDelta object { file_search, index, type, id }` + - `"direct"` - - `file_search: unknown` + - `"programmatic"` - For now, this is always going to be an empty object. + - `allowed_tools: optional array of string or object { read_only, tool_names }` - - `index: number` + List of allowed tool names or a filter object. - The index of the tool call in the tool calls array. + - `McpAllowedTools = array of string` - - `type: "file_search"` + A string array of allowed tool names - The type of tool call. This is always going to be `file_search` for this type of tool call. + - `McpToolFilter object { read_only, tool_names }` - - `"file_search"` + A filter object to specify which tools are allowed. - - `id: optional string` + - `read_only: optional boolean` - The ID of the tool call object. + 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. - - `FunctionToolCallDelta object { index, type, id, function }` + - `tool_names: optional array of string` - - `index: number` + List of allowed tool names. - The index of the tool call in the tool calls array. + - `authorization: optional string` - - `type: "function"` + An OAuth access token that can be used with a remote MCP server, either + with a custom MCP server URL or a service connector. Your application + must handle the OAuth authorization flow and provide the token here. - The type of tool call. This is always going to be `function` for this type of tool call. + - `connector_id: optional "connector_dropbox" or "connector_gmail" or "connector_googlecalendar" or 5 more` - - `"function"` + 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). - - `id: optional string` + Currently supported `connector_id` values are: - The ID of the tool call object. + - 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` - - `function: optional object { arguments, name, output }` + - `"connector_dropbox"` - The definition of the function that was called. + - `"connector_gmail"` - - `arguments: optional string` + - `"connector_googlecalendar"` - The arguments passed to the function. + - `"connector_googledrive"` - - `name: optional string` + - `"connector_microsoftteams"` - The name of the function. + - `"connector_outlookcalendar"` - - `output: optional string` + - `"connector_outlookemail"` - The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. + - `"connector_sharepoint"` - - `object: "thread.run.step.delta"` + - `defer_loading: optional boolean` - The object type, which is always `thread.run.step.delta`. + Whether this MCP tool is deferred and discovered via tool search. - - `"thread.run.step.delta"` + - `headers: optional map[string]` - - `event: "thread.run.step.delta"` + Optional HTTP headers to send to the MCP server. Use for authentication + or other purposes. - - `"thread.run.step.delta"` + - `require_approval: optional object { always, never } or "always" or "never"` - - `object { data, event }` + Specify which of the MCP server's tools require approval. - Occurs when a [run step](/docs/api-reference/run-steps/step-object) is completed. + - `McpToolApprovalFilter object { always, never }` - - `data: RunStep` + Specify which of the MCP server's tools require approval. Can be + `always`, `never`, or a filter object associated with tools + that require approval. - Represents a step in execution of a run. + - `always: optional object { read_only, tool_names }` - - `event: "thread.run.step.completed"` + A filter object to specify which tools are allowed. - - `"thread.run.step.completed"` + - `read_only: optional boolean` - - `object { data, event }` + 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. - Occurs when a [run step](/docs/api-reference/run-steps/step-object) fails. + - `tool_names: optional array of string` - - `data: RunStep` + List of allowed tool names. - Represents a step in execution of a run. + - `never: optional object { read_only, tool_names }` - - `event: "thread.run.step.failed"` + A filter object to specify which tools are allowed. - - `"thread.run.step.failed"` + - `read_only: optional boolean` - - `object { data, event }` + 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. - Occurs when a [run step](/docs/api-reference/run-steps/step-object) is cancelled. + - `tool_names: optional array of string` - - `data: RunStep` + List of allowed tool names. - Represents a step in execution of a run. + - `McpToolApprovalSetting = "always" or "never"` - - `event: "thread.run.step.cancelled"` + 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. - - `"thread.run.step.cancelled"` + - `"always"` - - `object { data, event }` + - `"never"` - Occurs when a [run step](/docs/api-reference/run-steps/step-object) expires. + - `server_description: optional string` - - `data: RunStep` + Optional description of the MCP server, used to provide more context. - Represents a step in execution of a run. + - `server_url: optional string` - - `event: "thread.run.step.expired"` + The URL for the MCP server. One of `server_url`, `connector_id`, or + `tunnel_id` must be provided. - - `"thread.run.step.expired"` + - `tunnel_id: optional string` -### Run Stream Event + 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. -- `RunStreamEvent = object { data, event } or object { data, event } or object { data, event } or 7 more` + - `CodeInterpreter object { container, type, allowed_callers }` - Occurs when a new [run](/docs/api-reference/runs/object) is created. + A tool that runs Python code to help generate a response to a prompt. - - `object { data, event }` + - `container: string or object { type, file_ids, memory_limit, network_policy }` - Occurs when a new [run](/docs/api-reference/runs/object) is created. + 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. - - `data: Run` + - `string` - Represents an execution run on a [thread](/docs/api-reference/threads). + The container ID. - - `id: string` + - `CodeInterpreterToolAuto object { type, file_ids, memory_limit, network_policy }` - The identifier, which can be referenced in API endpoints. + Configuration for a code interpreter container. Optionally specify the IDs of the files to run the code on. - - `assistant_id: string` + - `type: "auto"` - The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. + Always `auto`. - - `cancelled_at: number` + - `"auto"` - The Unix timestamp (in seconds) for when the run was cancelled. + - `file_ids: optional array of string` - - `completed_at: number` + An optional list of uploaded files to make available to your code. - The Unix timestamp (in seconds) for when the run was completed. + - `memory_limit: optional "1g" or "4g" or "16g" or "64g"` - - `created_at: number` + The memory limit for the code interpreter container. - The Unix timestamp (in seconds) for when the run was created. + - `"1g"` - - `expires_at: number` + - `"4g"` - The Unix timestamp (in seconds) for when the run will expire. + - `"16g"` - - `failed_at: number` + - `"64g"` - The Unix timestamp (in seconds) for when the run failed. + - `network_policy: optional BetaContainerNetworkPolicyDisabled or BetaContainerNetworkPolicyAllowlist` - - `incomplete_details: object { reason }` + Network access policy for the container. - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `BetaContainerNetworkPolicyDisabled object { type }` - - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` + - `BetaContainerNetworkPolicyAllowlist object { allowed_domains, type, domain_secrets }` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `type: "code_interpreter"` - - `"max_completion_tokens"` + The type of the code interpreter tool. Always `code_interpreter`. - - `"max_prompt_tokens"` + - `"code_interpreter"` - - `instructions: string` + - `allowed_callers: optional array of "direct" or "programmatic"` - The instructions that the [assistant](/docs/api-reference/assistants) used for this run. + The tool invocation context(s). - - `last_error: object { code, message }` + - `"direct"` - The last error associated with this run. Will be `null` if there are no errors. + - `"programmatic"` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` + - `ProgrammaticToolCalling object { type }` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `type: "programmatic_tool_calling"` - - `"server_error"` + The type of the tool. Always `programmatic_tool_calling`. - - `"rate_limit_exceeded"` + - `"programmatic_tool_calling"` - - `"invalid_prompt"` + - `ImageGeneration object { type, action, background, 9 more }` - - `message: string` + A tool that generates images using the GPT image models. - A human-readable description of the error. + - `type: "image_generation"` - - `max_completion_tokens: number` + The type of the image generation tool. Always `image_generation`. - The maximum number of completion tokens specified to have been used over the course of the run. + - `"image_generation"` - - `max_prompt_tokens: number` + - `action: optional "generate" or "edit" or "auto"` - The maximum number of prompt tokens specified to have been used over the course of the run. + Whether to generate a new image or edit an existing image. Default: `auto`. - - `metadata: Metadata` + - `"generate"` - 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. + - `"edit"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"auto"` - - `model: string` + - `background: optional "transparent" or "opaque" or "auto"` - The model that the [assistant](/docs/api-reference/assistants) used for this run. + Background type for the generated image. One of `transparent`, + `opaque`, or `auto`. Default: `auto`. - - `object: "thread.run"` + - `"transparent"` - The object type, which is always `thread.run`. + - `"opaque"` - - `"thread.run"` + - `"auto"` - - `parallel_tool_calls: boolean` + - `input_fidelity: optional "high" or "low"` - Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + 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`. - - `required_action: object { submit_tool_outputs, type }` + - `"high"` - Details on the action required to continue the run. Will be `null` if no action is required. + - `"low"` - - `submit_tool_outputs: object { tool_calls }` + - `input_image_mask: optional object { file_id, image_url }` - Details on the tool outputs needed for this run to continue. + Optional mask for inpainting. Contains `image_url` + (string, optional) and `file_id` (string, optional). - - `tool_calls: array of RequiredActionFunctionToolCall` + - `file_id: optional string` - A list of the relevant tool calls. + File ID for the mask image. - - `id: string` + - `image_url: optional string` - The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](/docs/api-reference/runs/submitToolOutputs) endpoint. + Base64-encoded mask image. - - `function: object { arguments, name }` + - `model: optional string or "gpt-image-1" or "gpt-image-1-mini" or "gpt-image-1.5"` - The function definition. + The image generation model to use. Default: `gpt-image-1`. - - `arguments: string` + - `string` - The arguments that the model expects you to pass to the function. + - `"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 function. + - `"gpt-image-1"` - - `type: "function"` + - `"gpt-image-1-mini"` - The type of tool call the output is required for. For now, this is always `function`. + - `"gpt-image-1.5"` - - `"function"` + - `moderation: optional "auto" or "low"` - - `type: "submit_tool_outputs"` + Moderation level for the generated image. Default: `auto`. - For now, this is always `submit_tool_outputs`. + - `"auto"` - - `"submit_tool_outputs"` + - `"low"` - - `response_format: AssistantResponseFormatOption` + - `output_compression: optional number` - Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + Compression level for the output image. Default: 100. - Setting to `{ "type": "json_schema", "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). + - `output_format: optional "png" or "webp" or "jpeg"` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + The output format of the generated image. One of `png`, `webp`, or + `jpeg`. Default: `png`. - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `"png"` - - `"auto"` + - `"webp"` - `auto` is the default value + - `"jpeg"` - - `"auto"` + - `partial_images: optional number` - - `ResponseFormatText object { type }` + Number of partial images to generate in streaming mode, from 0 (default value) to 3. - Default response format. Used to generate text responses. + - `quality: optional "low" or "medium" or "high" or "auto"` - - `type: "text"` + The quality of the generated image. One of `low`, `medium`, `high`, + or `auto`. Default: `auto`. - The type of response format being defined. Always `text`. + - `"low"` - - `"text"` + - `"medium"` - - `ResponseFormatJSONObject object { type }` + - `"high"` - 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. + - `"auto"` - - `type: "json_object"` + - `size: optional string or "1024x1024" or "1024x1536" or "1536x1024" or "auto"` - The type of response format being defined. Always `json_object`. + 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`. - - `"json_object"` + - `string` - - `ResponseFormatJSONSchema object { json_schema, type }` + - `"1024x1024" or "1024x1536" or "1536x1024" or "auto"` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + 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`. - - `json_schema: object { name, description, schema, strict }` + - `"1024x1024"` - Structured Outputs configuration options, including a JSON Schema. + - `"1024x1536"` - - `name: string` + - `"1536x1024"` - 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. + - `"auto"` - - `description: optional string` + - `LocalShell object { type }` - A description of what the response format is for, used by the model to - determine how to respond in the format. + A tool that allows the model to execute shell commands in a local environment. - - `schema: optional map[unknown]` + - `type: "local_shell"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The type of the local shell tool. Always `local_shell`. - - `strict: optional boolean` + - `"local_shell"` - 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). + - `Shell object { type, allowed_callers, environment }` - - `type: "json_schema"` + A tool that allows the model to execute shell commands. - The type of response format being defined. Always `json_schema`. + - `type: "shell"` - - `"json_schema"` + The type of the shell tool. Always `shell`. - - `started_at: number` + - `"shell"` - The Unix timestamp (in seconds) for when the run was started. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `status: "queued" or "in_progress" or "requires_action" or 6 more` + The tool invocation context(s). - The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + - `"direct"` - - `"queued"` + - `"programmatic"` - - `"in_progress"` + - `environment: optional BetaContainerAuto or BetaLocalEnvironment or BetaContainerReference` - - `"requires_action"` + - `BetaContainerAuto object { type, file_ids, memory_limit, 2 more }` - - `"cancelling"` + - `BetaLocalEnvironment object { type, skills }` - - `"cancelled"` + - `BetaContainerReference object { container_id, type }` - - `"failed"` + - `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) - - `"incomplete"` + - `name: string` - - `"expired"` + The name of the custom tool, used to identify it in tool calls. - - `thread_id: string` + - `type: "custom"` - The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. + The type of the custom tool. Always `custom`. - - `tool_choice: AssistantToolChoiceOption` + - `"custom"` - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"none" or "auto" or "required"` + The tool invocation context(s). - `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. + - `"direct"` - - `"none"` + - `"programmatic"` - - `"auto"` + - `defer_loading: optional boolean` - - `"required"` + Whether this tool should be deferred and discovered via tool search. - - `AssistantToolChoice object { type, function }` + - `description: optional string` - Specifies a tool the model should use. Use to force the model to call a specific tool. + Optional description of the custom tool, used to provide more context. - - `type: "function" or "code_interpreter" or "file_search"` + - `format: optional object { type } or object { definition, syntax, type }` - The type of the tool. If type is `function`, the function name must be set + The input format for the custom tool. Default is unconstrained text. - - `"function"` + - `Text object { type }` - - `"code_interpreter"` + Unconstrained free-form text. - - `"file_search"` + - `type: "text"` - - `function: optional AssistantToolChoiceFunction` + Unconstrained text format. Always `text`. - - `name: string` + - `"text"` - The name of the function to call. + - `Grammar object { definition, syntax, type }` - - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` + A grammar defined by the user. - The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. + - `definition: string` - - `CodeInterpreterTool object { type }` + The grammar definition. - - `type: "code_interpreter"` + - `syntax: "lark" or "regex"` - The type of tool being defined: `code_interpreter` + The syntax of the grammar definition. One of `lark` or `regex`. - - `"code_interpreter"` + - `"lark"` - - `FileSearchTool object { type, file_search }` + - `"regex"` - - `type: "file_search"` + - `type: "grammar"` - The type of tool being defined: `file_search` + Grammar format. Always `grammar`. - - `"file_search"` + - `"grammar"` - - `file_search: optional object { max_num_results, ranking_options }` + - `Namespace object { description, name, tools, type }` - Overrides for the file search tool. + Groups function/custom tools under a shared namespace. - - `max_num_results: optional number` + - `description: string` - The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + A description of the namespace shown to the model. - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `name: string` - - `ranking_options: optional object { score_threshold, ranker }` + The namespace name used in tool calls (for example, `crm`). - The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + - `tools: array of object { name, type, allowed_callers, 5 more } or object { name, type, allowed_callers, 3 more }` - See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + The function/custom tools available inside this namespace. - - `score_threshold: number` + - `Function object { name, type, allowed_callers, 5 more }` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `name: string` - - `ranker: optional "auto" or "default_2024_08_21"` + - `type: "function"` - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `"function"` - - `"auto"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"default_2024_08_21"` + The tool invocation context(s). - - `FunctionTool object { function, type }` + - `"direct"` - - `function: FunctionDefinition` + - `"programmatic"` - - `name: string` + - `defer_loading: optional boolean` - The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + Whether this function should be deferred and discovered via tool search. - `description: optional string` - A description of what the function does, used by the model to choose when and how to call the function. - - - `parameters: optional FunctionParameters` + - `output_schema: optional map[unknown]` - The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + A JSON Schema describing the JSON value encoded in string outputs for this function tool. This does not describe content-array outputs. - Omitting `parameters` defines a function with an empty parameter list. + - `parameters: optional unknown` - `strict: optional boolean` - Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-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. - - `type: "function"` + - `Custom object { name, type, allowed_callers, 3 more }` - The type of tool being defined: `function` + A custom tool that processes input using a specified format. Learn more about [custom tools](/docs/guides/function-calling#custom-tools) - - `"function"` + - `name: string` - - `truncation_strategy: object { type, last_messages }` + The name of the custom tool, used to identify it in tool calls. - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `type: "custom"` - - `type: "auto" or "last_messages"` + The type of the custom tool. Always `custom`. - The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + - `"custom"` - - `"auto"` + - `allowed_callers: optional array of "direct" or "programmatic"` - - `"last_messages"` + The tool invocation context(s). - - `last_messages: optional number` + - `"direct"` - The number of most recent messages from the thread when constructing the context for the run. + - `"programmatic"` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `defer_loading: optional boolean` - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + Whether this tool should be deferred and discovered via tool search. - - `completion_tokens: number` + - `description: optional string` - Number of completion tokens used over the course of the run. + Optional description of the custom tool, used to provide more context. - - `prompt_tokens: number` + - `format: optional object { type } or object { definition, syntax, type }` - Number of prompt tokens used over the course of the run. + The input format for the custom tool. Default is unconstrained text. - - `total_tokens: number` + - `Text object { type }` - Total number of tokens used (prompt + completion). + Unconstrained free-form text. - - `temperature: optional number` + - `type: "text"` - The sampling temperature used for this run. If not set, defaults to 1. + Unconstrained text format. Always `text`. - - `top_p: optional number` + - `"text"` - The nucleus sampling value used for this run. If not set, defaults to 1. + - `Grammar object { definition, syntax, type }` - - `event: "thread.run.created"` + A grammar defined by the user. - - `"thread.run.created"` + - `definition: string` - - `object { data, event }` + The grammar definition. - Occurs when a [run](/docs/api-reference/runs/object) moves to a `queued` status. + - `syntax: "lark" or "regex"` - - `data: Run` + The syntax of the grammar definition. One of `lark` or `regex`. - Represents an execution run on a [thread](/docs/api-reference/threads). + - `"lark"` - - `event: "thread.run.queued"` + - `"regex"` - - `"thread.run.queued"` + - `type: "grammar"` - - `object { data, event }` + Grammar format. Always `grammar`. - Occurs when a [run](/docs/api-reference/runs/object) moves to an `in_progress` status. + - `"grammar"` - - `data: Run` + - `type: "namespace"` - Represents an execution run on a [thread](/docs/api-reference/threads). + The type of the tool. Always `namespace`. - - `event: "thread.run.in_progress"` + - `"namespace"` - - `"thread.run.in_progress"` + - `ToolSearch object { type, description, execution, parameters }` - - `object { data, event }` + Hosted or BYOT tool search configuration for deferred tools. - Occurs when a [run](/docs/api-reference/runs/object) moves to a `requires_action` status. + - `type: "tool_search"` - - `data: Run` + The type of the tool. Always `tool_search`. - Represents an execution run on a [thread](/docs/api-reference/threads). + - `"tool_search"` - - `event: "thread.run.requires_action"` + - `description: optional string` - - `"thread.run.requires_action"` + Description shown to the model for a client-executed tool search tool. - - `object { data, event }` + - `execution: optional "server" or "client"` - Occurs when a [run](/docs/api-reference/runs/object) is completed. + Whether tool search is executed by the server or by the client. - - `data: Run` + - `"server"` - Represents an execution run on a [thread](/docs/api-reference/threads). + - `"client"` - - `event: "thread.run.completed"` + - `parameters: optional unknown` - - `"thread.run.completed"` + Parameter schema for a client-executed tool search tool. - - `object { data, event }` + - `WebSearchPreview object { type, search_content_types, search_context_size, user_location }` - Occurs when a [run](/docs/api-reference/runs/object) ends with status `incomplete`. + 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). - - `data: Run` + - `type: "web_search_preview" or "web_search_preview_2025_03_11"` - Represents an execution run on a [thread](/docs/api-reference/threads). + The type of the web search tool. One of `web_search_preview` or `web_search_preview_2025_03_11`. - - `event: "thread.run.incomplete"` + - `"web_search_preview"` - - `"thread.run.incomplete"` + - `"web_search_preview_2025_03_11"` - - `object { data, event }` + - `search_content_types: optional array of "text" or "image"` - Occurs when a [run](/docs/api-reference/runs/object) fails. + - `"text"` - - `data: Run` + - `"image"` - Represents an execution run on a [thread](/docs/api-reference/threads). + - `search_context_size: optional "low" or "medium" or "high"` - - `event: "thread.run.failed"` + 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. - - `"thread.run.failed"` + - `"low"` - - `object { data, event }` + - `"medium"` - Occurs when a [run](/docs/api-reference/runs/object) moves to a `cancelling` status. + - `"high"` - - `data: Run` + - `user_location: optional object { type, city, country, 2 more }` - Represents an execution run on a [thread](/docs/api-reference/threads). + The user's location. - - `event: "thread.run.cancelling"` + - `type: "approximate"` - - `"thread.run.cancelling"` + The type of location approximation. Always `approximate`. - - `object { data, event }` + - `"approximate"` - Occurs when a [run](/docs/api-reference/runs/object) is cancelled. + - `city: optional string` - - `data: Run` + Free text input for the city of the user, e.g. `San Francisco`. - Represents an execution run on a [thread](/docs/api-reference/threads). + - `country: optional string` - - `event: "thread.run.cancelled"` + The two-letter [ISO country code](https://en.wikipedia.org/wiki/ISO_3166-1) of the user, e.g. `US`. - - `"thread.run.cancelled"` + - `region: optional string` - - `object { data, event }` + Free text input for the region of the user, e.g. `California`. - Occurs when a [run](/docs/api-reference/runs/object) expires. + - `timezone: optional string` - - `data: Run` + The [IANA timezone](https://timeapi.io/documentation/iana-timezones) of the user, e.g. `America/Los_Angeles`. - Represents an execution run on a [thread](/docs/api-reference/threads). + - `ApplyPatch object { type, allowed_callers }` - - `event: "thread.run.expired"` + Allows the assistant to create, delete, or update files using unified diffs. - - `"thread.run.expired"` + - `type: "apply_patch"` -### Thread Stream Event + The type of the tool. Always `apply_patch`. -- `ThreadStreamEvent object { data, event, enabled }` + - `"apply_patch"` - Occurs when a new [thread](/docs/api-reference/threads/object) is created. + - `allowed_callers: optional array of "direct" or "programmatic"` - - `data: Thread` + The tool invocation context(s). - Represents a thread that contains [messages](/docs/api-reference/messages). + - `"direct"` - - `id: string` + - `"programmatic"` - The identifier, which can be referenced in API endpoints. +- `truncation: optional "auto" or "disabled"` - - `created_at: number` + 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. - The Unix timestamp (in seconds) for when the thread was created. + - `"auto"` - - `metadata: Metadata` + - `"disabled"` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. +### Returns - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. +- `input_tokens: number` - - `object: "thread"` +- `object: "response.input_tokens"` - The object type, which is always `thread`. + - `"response.input_tokens"` - - `"thread"` +### Example - - `tool_resources: object { code_interpreter, file_search }` +```http +curl https://api.openai.com/v1/responses/input_tokens \ + -X POST \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - A set of resources that are made available to the assistant's tools in this thread. The resources are specific to the type of tool. For example, the `code_interpreter` tool requires a list of file IDs, while the `file_search` tool requires a list of vector store IDs. +#### Response - - `code_interpreter: optional object { file_ids }` +```json +{ + "input_tokens": 123, + "object": "response.input_tokens" +} +``` - - `file_ids: optional array of string` +### Example - A list of [file](/docs/api-reference/files) IDs made available to the `code_interpreter` tool. There can be a maximum of 20 files associated with the tool. +```http +curl -X POST https://api.openai.com/v1/responses/input_tokens \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "model": "gpt-5", + "input": "Tell me a joke." + }' +``` - - `file_search: optional object { vector_store_ids }` +#### Response - - `vector_store_ids: optional array of string` +```json +{ + "object": "response.input_tokens", + "input_tokens": 11 +} +``` - The [vector store](/docs/api-reference/vector-stores/object) attached to this thread. There can be a maximum of 1 vector store attached to the thread. +## Domain Types - - `event: "thread.created"` +### Input Token Count Response - - `"thread.created"` +- `InputTokenCountResponse object { input_tokens, object }` - - `enabled: optional boolean` + - `input_tokens: number` - Whether to enable input audio transcription. + - `object: "response.input_tokens"` + + - `"response.input_tokens"` # Threads @@ -223243,7 +223243,7 @@ Create a thread. The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. - - `AutoChunkingStrategy object { type }` + - `Auto object { type }` The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`. @@ -223253,7 +223253,7 @@ Create a thread. - `"auto"` - - `StaticChunkingStrategy object { static, type }` + - `Static object { static, type }` - `static: object { chunk_overlap_tokens, max_chunk_size_tokens }` @@ -223793,7 +223793,7 @@ Create a thread and run it in one request. The chunking strategy used to chunk the file(s). If not set, will use the `auto` strategy. - - `AutoChunkingStrategy object { type }` + - `Auto object { type }` The default strategy. This strategy currently uses a `max_chunk_size_tokens` of `800` and `chunk_overlap_tokens` of `400`. @@ -223803,7 +223803,7 @@ Create a thread and run it in one request. - `"auto"` - - `StaticChunkingStrategy object { static, type }` + - `Static object { static, type }` - `static: object { chunk_overlap_tokens, max_chunk_size_tokens }` @@ -224672,6 +224672,67 @@ event: done data: [DONE] ``` +## Delete thread + +**delete** `/threads/{thread_id}` + +Delete a thread. + +### Path Parameters + +- `thread_id: string` + +### Returns + +- `ThreadDeleted object { id, deleted, object }` + + - `id: string` + + - `deleted: boolean` + + - `object: "thread.deleted"` + + - `"thread.deleted"` + +### Example + +```http +curl https://api.openai.com/v1/threads/$THREAD_ID \ + -X DELETE \ + -H 'OpenAI-Beta: assistants=v2' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` + +#### Response + +```json +{ + "id": "id", + "deleted": true, + "object": "thread.deleted" +} +``` + +### Example + +```http +curl https://api.openai.com/v1/threads/thread_abc123 \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" \ + -X DELETE +``` + +#### Response + +```json +{ + "id": "thread_abc123", + "object": "thread.deleted", + "deleted": true +} +``` + ## Retrieve thread **get** `/threads/{thread_id}` @@ -224932,67 +224993,6 @@ curl https://api.openai.com/v1/threads/thread_abc123 \ } ``` -## Delete thread - -**delete** `/threads/{thread_id}` - -Delete a thread. - -### Path Parameters - -- `thread_id: string` - -### Returns - -- `ThreadDeleted object { id, deleted, object }` - - - `id: string` - - - `deleted: boolean` - - - `object: "thread.deleted"` - - - `"thread.deleted"` - -### Example - -```http -curl https://api.openai.com/v1/threads/$THREAD_ID \ - -X DELETE \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` - -#### Response - -```json -{ - "id": "id", - "deleted": true, - "object": "thread.deleted" -} -``` - -### Example - -```http -curl https://api.openai.com/v1/threads/thread_abc123 \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: assistants=v2" \ - -X DELETE -``` - -#### Response - -```json -{ - "id": "thread_abc123", - "object": "thread.deleted", - "deleted": true -} -``` - ## Domain Types ### Assistant Response Format Option @@ -225201,770 +225201,599 @@ curl https://api.openai.com/v1/threads/thread_abc123 \ - `"thread.deleted"` -# Runs +# Messages -## List runs +## Create message -**get** `/threads/{thread_id}/runs` +**post** `/threads/{thread_id}/messages` -Returns a list of runs belonging to a thread. +Create a message. ### Path Parameters - `thread_id: string` -### Query Parameters - -- `after: optional string` - - A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. - -- `before: optional string` - - A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. - -- `limit: optional number` - - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - -- `order: optional "asc" or "desc"` - - Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. - - - `"asc"` - - - `"desc"` - -### Returns - -- `data: array of Run` - - - `id: string` - - The identifier, which can be referenced in API endpoints. - - - `assistant_id: string` - - The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. - - - `cancelled_at: number` - - The Unix timestamp (in seconds) for when the run was cancelled. - - - `completed_at: number` - - The Unix timestamp (in seconds) for when the run was completed. - - - `created_at: number` +### Body Parameters - The Unix timestamp (in seconds) for when the run was created. +- `content: string or array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlockParam` - - `expires_at: number` + The text contents of the message. - The Unix timestamp (in seconds) for when the run will expire. + - `TextContent = string` - - `failed_at: number` + The text contents of the message. - The Unix timestamp (in seconds) for when the run failed. + - `ArrayOfContentParts = array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlockParam` - - `incomplete_details: object { reason }` + An array of content parts with a defined type, each can be of type `text` or images can be passed with `image_url` or `image_file`. Image types are only supported on [Vision-compatible models](/docs/models). - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `ImageFileContentBlock object { image_file, type }` - - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` + References an image [File](/docs/api-reference/files) in the content of a message. - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `image_file: ImageFile` - - `"max_completion_tokens"` + - `file_id: string` - - `"max_prompt_tokens"` + The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `instructions: string` + - `detail: optional "auto" or "low" or "high"` - The instructions that the [assistant](/docs/api-reference/assistants) used for this run. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `last_error: object { code, message }` + - `"auto"` - The last error associated with this run. Will be `null` if there are no errors. + - `"low"` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` + - `"high"` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `type: "image_file"` - - `"server_error"` + Always `image_file`. - - `"rate_limit_exceeded"` + - `"image_file"` - - `"invalid_prompt"` + - `ImageURLContentBlock object { image_url, type }` - - `message: string` + References an image URL in the content of a message. - A human-readable description of the error. + - `image_url: ImageURL` - - `max_completion_tokens: number` + - `url: string` - The maximum number of completion tokens specified to have been used over the course of the run. + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `max_prompt_tokens: number` + - `detail: optional "auto" or "low" or "high"` - The maximum number of prompt tokens specified to have been used over the course of the run. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `metadata: Metadata` + - `"auto"` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `"low"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"high"` - - `model: string` + - `type: "image_url"` - The model that the [assistant](/docs/api-reference/assistants) used for this run. + The type of the content part. - - `object: "thread.run"` + - `"image_url"` - The object type, which is always `thread.run`. + - `TextContentBlockParam object { text, type }` - - `"thread.run"` + The text content that is part of a message. - - `parallel_tool_calls: boolean` + - `text: string` - Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + Text content to be sent to the model - - `required_action: object { submit_tool_outputs, type }` + - `type: "text"` - Details on the action required to continue the run. Will be `null` if no action is required. + Always `text`. - - `submit_tool_outputs: object { tool_calls }` + - `"text"` - Details on the tool outputs needed for this run to continue. +- `role: "user" or "assistant"` - - `tool_calls: array of RequiredActionFunctionToolCall` + The role of the entity that is creating the message. Allowed values include: - A list of the relevant tool calls. + - `user`: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages. + - `assistant`: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation. - - `id: string` + - `"user"` - The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](/docs/api-reference/runs/submitToolOutputs) endpoint. + - `"assistant"` - - `function: object { arguments, name }` +- `attachments: optional array of object { file_id, tools }` - The function definition. + A list of files attached to the message, and the tools they should be added to. - - `arguments: string` + - `file_id: optional string` - The arguments that the model expects you to pass to the function. + The ID of the file to attach to the message. - - `name: string` + - `tools: optional array of CodeInterpreterTool or object { type }` - The name of the function. + The tools to add this file to. - - `type: "function"` + - `CodeInterpreterTool object { type }` - The type of tool call the output is required for. For now, this is always `function`. + - `type: "code_interpreter"` - - `"function"` + The type of tool being defined: `code_interpreter` - - `type: "submit_tool_outputs"` + - `"code_interpreter"` - For now, this is always `submit_tool_outputs`. + - `FileSearchTool object { type }` - - `"submit_tool_outputs"` + - `type: "file_search"` - - `response_format: AssistantResponseFormatOption` + The type of tool being defined: `file_search` - Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `"file_search"` - Setting to `{ "type": "json_schema", "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). +- `metadata: optional Metadata` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + 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. - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"auto"` +### Returns - `auto` is the default value +- `Message object { id, assistant_id, attachments, 11 more }` - - `"auto"` + Represents a message within a [thread](/docs/api-reference/threads). - - `ResponseFormatText object { type }` + - `id: string` - Default response format. Used to generate text responses. + The identifier, which can be referenced in API endpoints. - - `type: "text"` + - `assistant_id: string` - The type of response format being defined. Always `text`. + If applicable, the ID of the [assistant](/docs/api-reference/assistants) that authored this message. - - `"text"` + - `attachments: array of object { file_id, tools }` - - `ResponseFormatJSONObject object { type }` + A list of files attached to the message, and the tools they were added to. - 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. + - `file_id: optional string` - - `type: "json_object"` + The ID of the file to attach to the message. - The type of response format being defined. Always `json_object`. + - `tools: optional array of CodeInterpreterTool or object { type }` - - `"json_object"` + The tools to add this file to. - - `ResponseFormatJSONSchema object { json_schema, type }` + - `CodeInterpreterTool object { type }` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + - `type: "code_interpreter"` - - `json_schema: object { name, description, schema, strict }` + The type of tool being defined: `code_interpreter` - Structured Outputs configuration options, including a JSON Schema. + - `"code_interpreter"` - - `name: string` + - `FileSearchTool object { 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. + - `type: "file_search"` - - `description: optional string` + The type of tool being defined: `file_search` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `"file_search"` - - `schema: optional map[unknown]` + - `completed_at: 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 Unix timestamp (in seconds) for when the message was completed. - - `strict: optional boolean` + - `content: array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlock or RefusalContentBlock` - 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 content of the message in array of text and/or images. - - `type: "json_schema"` + - `ImageFileContentBlock object { image_file, type }` - The type of response format being defined. Always `json_schema`. + References an image [File](/docs/api-reference/files) in the content of a message. - - `"json_schema"` + - `image_file: ImageFile` - - `started_at: number` + - `file_id: string` - The Unix timestamp (in seconds) for when the run was started. + The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `status: "queued" or "in_progress" or "requires_action" or 6 more` + - `detail: optional "auto" or "low" or "high"` - The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `"queued"` + - `"auto"` - - `"in_progress"` + - `"low"` - - `"requires_action"` + - `"high"` - - `"cancelling"` + - `type: "image_file"` - - `"cancelled"` + Always `image_file`. - - `"failed"` + - `"image_file"` - - `"completed"` + - `ImageURLContentBlock object { image_url, type }` - - `"incomplete"` + References an image URL in the content of a message. - - `"expired"` + - `image_url: ImageURL` - - `thread_id: string` + - `url: string` - The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `tool_choice: AssistantToolChoiceOption` + - `detail: optional "auto" or "low" or "high"` - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `"none" or "auto" or "required"` + - `"auto"` - `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. + - `"low"` - - `"none"` + - `"high"` - - `"auto"` + - `type: "image_url"` - - `"required"` + The type of the content part. - - `AssistantToolChoice object { type, function }` + - `"image_url"` - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `TextContentBlock object { text, type }` - - `type: "function" or "code_interpreter" or "file_search"` + The text content that is part of a message. - The type of the tool. If type is `function`, the function name must be set + - `text: Text` - - `"function"` + - `annotations: array of FileCitationAnnotation or FilePathAnnotation` - - `"code_interpreter"` + - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` - - `"file_search"` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `function: optional AssistantToolChoiceFunction` + - `end_index: number` - - `name: string` + - `file_citation: object { file_id }` - The name of the function to call. + - `file_id: string` - - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` + The ID of the specific File the citation is from. - The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. + - `start_index: number` - - `CodeInterpreterTool object { type }` + - `text: string` - - `type: "code_interpreter"` + The text in the message content that needs to be replaced. - The type of tool being defined: `code_interpreter` + - `type: "file_citation"` - - `"code_interpreter"` + Always `file_citation`. - - `FileSearchTool object { type, file_search }` + - `"file_citation"` - - `type: "file_search"` + - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` - The type of tool being defined: `file_search` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `"file_search"` + - `end_index: number` - - `file_search: optional object { max_num_results, ranking_options }` + - `file_path: object { file_id }` - Overrides for the file search tool. + - `file_id: string` - - `max_num_results: optional number` + The ID of the file that was generated. - The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + - `start_index: number` - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `text: string` - - `ranking_options: optional object { score_threshold, ranker }` + The text in the message content that needs to be replaced. - The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + - `type: "file_path"` - See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + Always `file_path`. - - `score_threshold: number` + - `"file_path"` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `value: string` - - `ranker: optional "auto" or "default_2024_08_21"` + The data that makes up the text. - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `type: "text"` - - `"auto"` + Always `text`. - - `"default_2024_08_21"` + - `"text"` - - `FunctionTool object { function, type }` + - `RefusalContentBlock object { refusal, type }` - - `function: FunctionDefinition` + The refusal content generated by the assistant. - - `name: string` + - `refusal: string` - The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + - `type: "refusal"` - - `description: optional string` + Always `refusal`. - A description of what the function does, used by the model to choose when and how to call the function. + - `"refusal"` - - `parameters: optional FunctionParameters` + - `created_at: number` - The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + The Unix timestamp (in seconds) for when the message was created. - Omitting `parameters` defines a function with an empty parameter list. + - `incomplete_at: number` - - `strict: optional boolean` + The Unix timestamp (in seconds) for when the message was marked as incomplete. - Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-calling). + - `incomplete_details: object { reason }` - - `type: "function"` + On an incomplete message, details about why the message is incomplete. - The type of tool being defined: `function` + - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` - - `"function"` + The reason the message is incomplete. - - `truncation_strategy: object { type, last_messages }` + - `"content_filter"` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `"max_tokens"` - - `type: "auto" or "last_messages"` + - `"run_cancelled"` - The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + - `"run_expired"` - - `"auto"` + - `"run_failed"` - - `"last_messages"` + - `metadata: Metadata` - - `last_messages: optional number` + Set of 16 key-value pairs that can be attached to an object. This can be + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - The number of most recent messages from the thread when constructing the context for the run. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `object: "thread.message"` - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + The object type, which is always `thread.message`. - - `completion_tokens: number` + - `"thread.message"` - Number of completion tokens used over the course of the run. + - `role: "user" or "assistant"` - - `prompt_tokens: number` + The entity that produced the message. One of `user` or `assistant`. - Number of prompt tokens used over the course of the run. + - `"user"` - - `total_tokens: number` + - `"assistant"` - Total number of tokens used (prompt + completion). + - `run_id: string` - - `temperature: optional number` + The ID of the [run](/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. - The sampling temperature used for this run. If not set, defaults to 1. + - `status: "in_progress" or "incomplete" or "completed"` - - `top_p: optional number` + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - The nucleus sampling value used for this run. If not set, defaults to 1. + - `"in_progress"` -- `first_id: string` + - `"incomplete"` -- `has_more: boolean` + - `"completed"` -- `last_id: string` + - `thread_id: string` -- `object: string` + The [thread](/docs/api-reference/threads) ID that this message belongs to. ### Example ```http -curl https://api.openai.com/v1/threads/$THREAD_ID/runs \ +curl https://api.openai.com/v1/threads/$THREAD_ID/messages \ + -H 'Content-Type: application/json' \ -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "content": "string", + "role": "user" + }' ``` #### Response ```json { - "data": [ - { "id": "id", "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expires_at": 0, - "failed_at": 0, - "incomplete_details": { - "reason": "max_completion_tokens" - }, - "instructions": "instructions", - "last_error": { - "code": "server_error", - "message": "message" - }, - "max_completion_tokens": 256, - "max_prompt_tokens": 256, - "metadata": { - "foo": "string" - }, - "model": "model", - "object": "thread.run", - "parallel_tool_calls": true, - "required_action": { - "submit_tool_outputs": { - "tool_calls": [ + "attachments": [ { - "id": "id", - "function": { - "arguments": "arguments", - "name": "name" - }, - "type": "function" - } - ] - }, - "type": "submit_tool_outputs" - }, - "response_format": "auto", - "started_at": 0, - "status": "queued", - "thread_id": "thread_id", - "tool_choice": "none", + "file_id": "file_id", "tools": [ { "type": "code_interpreter" } + ] + } ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 + "completed_at": 0, + "content": [ + { + "image_file": { + "file_id": "file_id", + "detail": "auto" }, - "temperature": 0, - "top_p": 0 + "type": "image_file" } ], - "first_id": "run_abc123", - "has_more": false, - "last_id": "run_abc456", - "object": "list" + "created_at": 0, + "incomplete_at": 0, + "incomplete_details": { + "reason": "content_filter" + }, + "metadata": { + "foo": "string" + }, + "object": "thread.message", + "role": "user", + "run_id": "run_id", + "status": "in_progress", + "thread_id": "thread_id" } ``` ### Example ```http -curl https://api.openai.com/v1/threads/thread_abc123/runs \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ +curl https://api.openai.com/v1/threads/thread_abc123/messages \ -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "role": "user", + "content": "How does AI work? Explain it in simple terms." + }' ``` #### Response ```json { - "object": "list", - "data": [ - { - "id": "run_abc123", - "object": "thread.run", - "created_at": 1699075072, - "assistant_id": "asst_abc123", - "thread_id": "thread_abc123", - "status": "completed", - "started_at": 1699075072, - "expires_at": null, - "cancelled_at": null, - "failed_at": null, - "completed_at": 1699075073, - "last_error": null, - "model": "gpt-4o", - "instructions": null, - "incomplete_details": null, - "tools": [ - { - "type": "code_interpreter" - } - ], - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "file-abc123", - "file-abc456" - ] - } - }, - "metadata": {}, - "usage": { - "prompt_tokens": 123, - "completion_tokens": 456, - "total_tokens": 579 - }, - "temperature": 1.0, - "top_p": 1.0, - "max_prompt_tokens": 1000, - "max_completion_tokens": 1000, - "truncation_strategy": { - "type": "auto", - "last_messages": null - }, - "response_format": "auto", - "tool_choice": "auto", - "parallel_tool_calls": true - }, - { - "id": "run_abc456", - "object": "thread.run", - "created_at": 1699063290, - "assistant_id": "asst_abc123", - "thread_id": "thread_abc123", - "status": "completed", - "started_at": 1699063290, - "expires_at": null, - "cancelled_at": null, - "failed_at": null, - "completed_at": 1699063291, - "last_error": null, - "model": "gpt-4o", - "instructions": null, - "incomplete_details": null, - "tools": [ - { - "type": "code_interpreter" - } - ], - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "file-abc123", - "file-abc456" - ] - } - }, - "metadata": {}, - "usage": { - "prompt_tokens": 123, - "completion_tokens": 456, - "total_tokens": 579 - }, - "temperature": 1.0, - "top_p": 1.0, - "max_prompt_tokens": 1000, - "max_completion_tokens": 1000, - "truncation_strategy": { - "type": "auto", - "last_messages": null - }, - "response_format": "auto", - "tool_choice": "auto", - "parallel_tool_calls": true - } - ], - "first_id": "run_abc123", - "last_id": "run_abc456", - "has_more": false -} -``` - -## Create run - -**post** `/threads/{thread_id}/runs` - -Create a run. - -### Path Parameters - -- `thread_id: string` - -### Query Parameters - -- `include: optional array of RunStepInclude` - - A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. - - See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - - `"step_details.tool_calls[*].file_search.results[*].content"` - -### Body Parameters - -- `assistant_id: string` - - The ID of the [assistant](/docs/api-reference/assistants) to use to execute this run. - -- `additional_instructions: optional string` - - Appends additional instructions at the end of the instructions for the run. This is useful for modifying the behavior on a per-run basis without overriding other instructions. - -- `additional_messages: optional array of object { content, role, attachments, metadata }` - - Adds additional messages to the thread before creating the run. + "id": "msg_abc123", + "object": "thread.message", + "created_at": 1713226573, + "assistant_id": null, + "thread_id": "thread_abc123", + "run_id": null, + "role": "user", + "content": [ + { + "type": "text", + "text": { + "value": "How does AI work? Explain it in simple terms.", + "annotations": [] + } + } + ], + "attachments": [], + "metadata": {} +} +``` - - `content: string or array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlockParam` +## Delete message - The text contents of the message. +**delete** `/threads/{thread_id}/messages/{message_id}` - - `TextContent = string` +Deletes a message. - The text contents of the message. +### Path Parameters - - `ArrayOfContentParts = array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlockParam` +- `thread_id: string` - An array of content parts with a defined type, each can be of type `text` or images can be passed with `image_url` or `image_file`. Image types are only supported on [Vision-compatible models](/docs/models). +- `message_id: string` - - `ImageFileContentBlock object { image_file, type }` +### Returns - References an image [File](/docs/api-reference/files) in the content of a message. +- `MessageDeleted object { id, deleted, object }` - - `image_file: ImageFile` + - `id: string` - - `file_id: string` + - `deleted: boolean` - The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + - `object: "thread.message.deleted"` - - `detail: optional "auto" or "low" or "high"` + - `"thread.message.deleted"` - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. +### Example - - `"auto"` +```http +curl https://api.openai.com/v1/threads/$THREAD_ID/messages/$MESSAGE_ID \ + -X DELETE \ + -H 'OpenAI-Beta: assistants=v2' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `"low"` +#### Response - - `"high"` +```json +{ + "id": "id", + "deleted": true, + "object": "thread.message.deleted" +} +``` - - `type: "image_file"` +### Example - Always `image_file`. +```http +curl -X DELETE https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" +``` - - `"image_file"` +#### Response - - `ImageURLContentBlock object { image_url, type }` +```json +{ + "id": "msg_abc123", + "object": "thread.message.deleted", + "deleted": true +} +``` - References an image URL in the content of a message. +## List messages - - `image_url: ImageURL` +**get** `/threads/{thread_id}/messages` - - `url: string` +Returns a list of messages for a given thread. - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. +### Path Parameters - - `detail: optional "auto" or "low" or "high"` +- `thread_id: string` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` +### Query Parameters - - `"auto"` +- `after: optional string` - - `"low"` + A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. - - `"high"` +- `before: optional string` - - `type: "image_url"` + A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. - The type of the content part. +- `limit: optional number` - - `"image_url"` + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. - - `TextContentBlockParam object { text, type }` +- `order: optional "asc" or "desc"` - The text content that is part of a message. + Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. - - `text: string` + - `"asc"` - Text content to be sent to the model + - `"desc"` - - `type: "text"` +- `run_id: optional string` - Always `text`. + Filter messages by the run ID that generated them. - - `"text"` +### Returns - - `role: "user" or "assistant"` +- `data: array of Message` - The role of the entity that is creating the message. Allowed values include: + - `id: string` - - `user`: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages. - - `assistant`: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation. + The identifier, which can be referenced in API endpoints. - - `"user"` + - `assistant_id: string` - - `"assistant"` + If applicable, the ID of the [assistant](/docs/api-reference/assistants) that authored this message. - - `attachments: optional array of object { file_id, tools }` + - `attachments: array of object { file_id, tools }` - A list of files attached to the message, and the tools they should be added to. + A list of files attached to the message, and the tools they were added to. - `file_id: optional string` @@ -225990,288 +225819,386 @@ Create a run. - `"file_search"` - - `metadata: optional Metadata` + - `completed_at: number` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + The Unix timestamp (in seconds) for when the message was completed. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `content: array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlock or RefusalContentBlock` -- `instructions: optional string` + The content of the message in array of text and/or images. - Overrides the [instructions](/docs/api-reference/assistants/createAssistant) of the assistant. This is useful for modifying the behavior on a per-run basis. + - `ImageFileContentBlock object { image_file, type }` -- `max_completion_tokens: optional number` + References an image [File](/docs/api-reference/files) in the content of a message. - The maximum number of completion tokens that may be used over the course of the run. The run will make a best effort to use only the number of completion tokens specified, across multiple turns of the run. If the run exceeds the number of completion tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info. + - `image_file: ImageFile` -- `max_prompt_tokens: optional number` + - `file_id: string` - The maximum number of prompt tokens that may be used over the course of the run. The run will make a best effort to use only the number of prompt tokens specified, across multiple turns of the run. If the run exceeds the number of prompt tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info. + The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. -- `metadata: optional Metadata` + - `detail: optional "auto" or "low" or "high"` - 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. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"auto"` -- `model: optional string or "gpt-5" or "gpt-5-mini" or "gpt-5-nano" or 39 more` + - `"low"` - The ID of the [Model](/docs/api-reference/models) to be used to execute this run. If a value is provided here, it will override the model associated with the assistant. If not, the model associated with the assistant will be used. + - `"high"` - - `string` + - `type: "image_file"` - - `AssistantSupportedModels = "gpt-5" or "gpt-5-mini" or "gpt-5-nano" or 39 more` + Always `image_file`. - The ID of the [Model](/docs/api-reference/models) to be used to execute this run. If a value is provided here, it will override the model associated with the assistant. If not, the model associated with the assistant will be used. + - `"image_file"` - - `"gpt-5"` + - `ImageURLContentBlock object { image_url, type }` - - `"gpt-5-mini"` + References an image URL in the content of a message. - - `"gpt-5-nano"` + - `image_url: ImageURL` - - `"gpt-5-2025-08-07"` + - `url: string` - - `"gpt-5-mini-2025-08-07"` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `"gpt-5-nano-2025-08-07"` + - `detail: optional "auto" or "low" or "high"` - - `"gpt-4.1"` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `"gpt-4.1-mini"` + - `"auto"` - - `"gpt-4.1-nano"` + - `"low"` - - `"gpt-4.1-2025-04-14"` + - `"high"` - - `"gpt-4.1-mini-2025-04-14"` + - `type: "image_url"` - - `"gpt-4.1-nano-2025-04-14"` + The type of the content part. - - `"o3-mini"` + - `"image_url"` - - `"o3-mini-2025-01-31"` + - `TextContentBlock object { text, type }` - - `"o1"` + The text content that is part of a message. - - `"o1-2024-12-17"` + - `text: Text` - - `"gpt-4o"` + - `annotations: array of FileCitationAnnotation or FilePathAnnotation` - - `"gpt-4o-2024-11-20"` + - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` - - `"gpt-4o-2024-08-06"` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `"gpt-4o-2024-05-13"` + - `end_index: number` - - `"gpt-4o-mini"` + - `file_citation: object { file_id }` - - `"gpt-4o-mini-2024-07-18"` + - `file_id: string` - - `"gpt-4.5-preview"` + The ID of the specific File the citation is from. - - `"gpt-4.5-preview-2025-02-27"` + - `start_index: number` - - `"gpt-4-turbo"` + - `text: string` - - `"gpt-4-turbo-2024-04-09"` + The text in the message content that needs to be replaced. - - `"gpt-4-0125-preview"` + - `type: "file_citation"` - - `"gpt-4-turbo-preview"` + Always `file_citation`. - - `"gpt-4-1106-preview"` + - `"file_citation"` - - `"gpt-4-vision-preview"` + - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` - - `"gpt-4"` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `"gpt-4-0314"` + - `end_index: number` - - `"gpt-4-0613"` + - `file_path: object { file_id }` - - `"gpt-4-32k"` + - `file_id: string` - - `"gpt-4-32k-0314"` + The ID of the file that was generated. - - `"gpt-4-32k-0613"` + - `start_index: number` - - `"gpt-3.5-turbo"` + - `text: string` - - `"gpt-3.5-turbo-16k"` + The text in the message content that needs to be replaced. - - `"gpt-3.5-turbo-0613"` + - `type: "file_path"` - - `"gpt-3.5-turbo-1106"` + Always `file_path`. - - `"gpt-3.5-turbo-0125"` + - `"file_path"` - - `"gpt-3.5-turbo-16k-0613"` + - `value: string` -- `parallel_tool_calls: optional boolean` + The data that makes up the text. - Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `type: "text"` -- `reasoning_effort: optional ReasoningEffort` + Always `text`. - 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. + - `"text"` - - `"none"` + - `RefusalContentBlock object { refusal, type }` - - `"minimal"` + The refusal content generated by the assistant. - - `"low"` + - `refusal: string` - - `"medium"` + - `type: "refusal"` - - `"high"` + Always `refusal`. - - `"xhigh"` + - `"refusal"` - - `"max"` + - `created_at: number` -- `response_format: optional AssistantResponseFormatOption` + The Unix timestamp (in seconds) for when the message was created. - Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `incomplete_at: number` - Setting to `{ "type": "json_schema", "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 Unix timestamp (in seconds) for when the message was marked as incomplete. - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `incomplete_details: object { reason }` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + On an incomplete message, details about why the message is incomplete. - - `"auto"` + - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` - `auto` is the default value + The reason the message is incomplete. - - `"auto"` + - `"content_filter"` - - `ResponseFormatText object { type }` + - `"max_tokens"` - Default response format. Used to generate text responses. + - `"run_cancelled"` - - `type: "text"` + - `"run_expired"` - The type of response format being defined. Always `text`. + - `"run_failed"` - - `"text"` + - `metadata: Metadata` - - `ResponseFormatJSONObject object { 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. - 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. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `type: "json_object"` + - `object: "thread.message"` - The type of response format being defined. Always `json_object`. + The object type, which is always `thread.message`. - - `"json_object"` + - `"thread.message"` - - `ResponseFormatJSONSchema object { json_schema, type }` + - `role: "user" or "assistant"` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + The entity that produced the message. One of `user` or `assistant`. - - `json_schema: object { name, description, schema, strict }` + - `"user"` - Structured Outputs configuration options, including a JSON Schema. + - `"assistant"` - - `name: string` + - `run_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 [run](/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. - - `description: optional string` + - `status: "in_progress" or "incomplete" or "completed"` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - - `schema: optional map[unknown]` + - `"in_progress"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + - `"incomplete"` - - `strict: optional boolean` + - `"completed"` - 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). + - `thread_id: string` - - `type: "json_schema"` + The [thread](/docs/api-reference/threads) ID that this message belongs to. - The type of response format being defined. Always `json_schema`. +- `first_id: string` - - `"json_schema"` +- `has_more: boolean` -- `stream: optional boolean` +- `last_id: string` - If `true`, returns a stream of events that happen during the Run as server-sent events, terminating when the Run enters a terminal state with a `data: [DONE]` message. +- `object: string` -- `temperature: optional number` +### Example - 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. +```http +curl https://api.openai.com/v1/threads/$THREAD_ID/messages \ + -H 'OpenAI-Beta: assistants=v2' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` -- `tool_choice: optional AssistantToolChoiceOption` +#### Response - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. +```json +{ + "data": [ + { + "id": "id", + "assistant_id": "assistant_id", + "attachments": [ + { + "file_id": "file_id", + "tools": [ + { + "type": "code_interpreter" + } + ] + } + ], + "completed_at": 0, + "content": [ + { + "image_file": { + "file_id": "file_id", + "detail": "auto" + }, + "type": "image_file" + } + ], + "created_at": 0, + "incomplete_at": 0, + "incomplete_details": { + "reason": "content_filter" + }, + "metadata": { + "foo": "string" + }, + "object": "thread.message", + "role": "user", + "run_id": "run_id", + "status": "in_progress", + "thread_id": "thread_id" + } + ], + "first_id": "msg_abc123", + "has_more": false, + "last_id": "msg_abc123", + "object": "list" +} +``` - - `"none" or "auto" or "required"` +### Example - `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. +```http +curl https://api.openai.com/v1/threads/thread_abc123/messages \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" +``` - - `"none"` +#### Response - - `"auto"` +```json +{ + "object": "list", + "data": [ + { + "id": "msg_abc123", + "object": "thread.message", + "created_at": 1699016383, + "assistant_id": null, + "thread_id": "thread_abc123", + "run_id": null, + "role": "user", + "content": [ + { + "type": "text", + "text": { + "value": "How does AI work? Explain it in simple terms.", + "annotations": [] + } + } + ], + "attachments": [], + "metadata": {} + }, + { + "id": "msg_abc456", + "object": "thread.message", + "created_at": 1699016383, + "assistant_id": null, + "thread_id": "thread_abc123", + "run_id": null, + "role": "user", + "content": [ + { + "type": "text", + "text": { + "value": "Hello, what is AI?", + "annotations": [] + } + } + ], + "attachments": [], + "metadata": {} + } + ], + "first_id": "msg_abc123", + "last_id": "msg_abc456", + "has_more": false +} +``` - - `"required"` +## Retrieve message - - `AssistantToolChoice object { type, function }` +**get** `/threads/{thread_id}/messages/{message_id}` - Specifies a tool the model should use. Use to force the model to call a specific tool. +Retrieve a message. - - `type: "function" or "code_interpreter" or "file_search"` +### Path Parameters - The type of the tool. If type is `function`, the function name must be set +- `thread_id: string` - - `"function"` +- `message_id: string` - - `"code_interpreter"` +### Returns - - `"file_search"` +- `Message object { id, assistant_id, attachments, 11 more }` - - `function: optional AssistantToolChoiceFunction` + Represents a message within a [thread](/docs/api-reference/threads). - - `name: string` + - `id: string` - The name of the function to call. + The identifier, which can be referenced in API endpoints. -- `tools: optional array of CodeInterpreterTool or FileSearchTool or FunctionTool` + - `assistant_id: string` - Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis. + If applicable, the ID of the [assistant](/docs/api-reference/assistants) that authored this message. + + - `attachments: array of object { file_id, tools }` + + A list of files attached to the message, and the tools they were added to. + + - `file_id: optional string` + + The ID of the file to attach to the message. + + - `tools: optional array of CodeInterpreterTool or object { type }` + + The tools to add this file to. - `CodeInterpreterTool object { type }` - - `FileSearchTool object { type, file_search }` + - `type: "code_interpreter"` + + The type of tool being defined: `code_interpreter` + + - `"code_interpreter"` + + - `FileSearchTool object { type }` - `type: "file_search"` @@ -226279,159 +226206,169 @@ Create a run. - `"file_search"` - - `file_search: optional object { max_num_results, ranking_options }` - - Overrides for the file search tool. + - `completed_at: number` - - `max_num_results: optional number` + The Unix timestamp (in seconds) for when the message was completed. - The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + - `content: array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlock or RefusalContentBlock` - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + The content of the message in array of text and/or images. - - `ranking_options: optional object { score_threshold, ranker }` + - `ImageFileContentBlock object { image_file, type }` - The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + References an image [File](/docs/api-reference/files) in the content of a message. - See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `image_file: ImageFile` - - `score_threshold: number` + - `file_id: string` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `ranker: optional "auto" or "default_2024_08_21"` + - `detail: optional "auto" or "low" or "high"` - The ranker to use for the file search. If not specified will use the `auto` ranker. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - `"auto"` - - `"default_2024_08_21"` + - `"low"` - - `FunctionTool object { function, type }` + - `"high"` - - `function: FunctionDefinition` + - `type: "image_file"` - - `name: string` + Always `image_file`. - The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + - `"image_file"` - - `description: optional string` + - `ImageURLContentBlock object { image_url, type }` - A description of what the function does, used by the model to choose when and how to call the function. + References an image URL in the content of a message. - - `parameters: optional FunctionParameters` + - `image_url: ImageURL` - The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + - `url: string` - Omitting `parameters` defines a function with an empty parameter list. + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `strict: optional boolean` + - `detail: optional "auto" or "low" or "high"` - Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-calling). + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - - `type: "function"` + - `"auto"` - The type of tool being defined: `function` + - `"low"` - - `"function"` + - `"high"` -- `top_p: optional number` + - `type: "image_url"` - 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 type of the content part. - We generally recommend altering this or temperature but not both. + - `"image_url"` -- `truncation_strategy: optional object { type, last_messages }` + - `TextContentBlock object { text, type }` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + The text content that is part of a message. - - `type: "auto" or "last_messages"` + - `text: Text` - The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + - `annotations: array of FileCitationAnnotation or FilePathAnnotation` - - `"auto"` + - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` - - `"last_messages"` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `last_messages: optional number` + - `end_index: number` - The number of most recent messages from the thread when constructing the context for the run. + - `file_citation: object { file_id }` -### Returns + - `file_id: string` -- `Run object { id, assistant_id, cancelled_at, 24 more }` + The ID of the specific File the citation is from. - Represents an execution run on a [thread](/docs/api-reference/threads). + - `start_index: number` - - `id: string` + - `text: string` - The identifier, which can be referenced in API endpoints. + The text in the message content that needs to be replaced. - - `assistant_id: string` + - `type: "file_citation"` - The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. + Always `file_citation`. - - `cancelled_at: number` + - `"file_citation"` - The Unix timestamp (in seconds) for when the run was cancelled. + - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` - - `completed_at: number` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - The Unix timestamp (in seconds) for when the run was completed. + - `end_index: number` - - `created_at: number` + - `file_path: object { file_id }` - The Unix timestamp (in seconds) for when the run was created. + - `file_id: string` - - `expires_at: number` + The ID of the file that was generated. - The Unix timestamp (in seconds) for when the run will expire. + - `start_index: number` - - `failed_at: number` + - `text: string` - The Unix timestamp (in seconds) for when the run failed. + The text in the message content that needs to be replaced. - - `incomplete_details: object { reason }` + - `type: "file_path"` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + Always `file_path`. - - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` + - `"file_path"` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `value: string` - - `"max_completion_tokens"` + The data that makes up the text. - - `"max_prompt_tokens"` + - `type: "text"` - - `instructions: string` + Always `text`. - The instructions that the [assistant](/docs/api-reference/assistants) used for this run. + - `"text"` - - `last_error: object { code, message }` + - `RefusalContentBlock object { refusal, type }` - The last error associated with this run. Will be `null` if there are no errors. + The refusal content generated by the assistant. - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` + - `refusal: string` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `type: "refusal"` - - `"server_error"` + Always `refusal`. - - `"rate_limit_exceeded"` + - `"refusal"` - - `"invalid_prompt"` + - `created_at: number` - - `message: string` + The Unix timestamp (in seconds) for when the message was created. - A human-readable description of the error. + - `incomplete_at: number` - - `max_completion_tokens: number` + The Unix timestamp (in seconds) for when the message was marked as incomplete. - The maximum number of completion tokens specified to have been used over the course of the run. + - `incomplete_details: object { reason }` - - `max_prompt_tokens: number` + On an incomplete message, details about why the message is incomplete. - The maximum number of prompt tokens specified to have been used over the course of the run. + - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` + + The reason the message is incomplete. + + - `"content_filter"` + + - `"max_tokens"` + + - `"run_cancelled"` + + - `"run_expired"` + + - `"run_failed"` - `metadata: Metadata` @@ -226442,333 +226379,400 @@ Create a run. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. - - `model: string` - - The model that the [assistant](/docs/api-reference/assistants) used for this run. + - `object: "thread.message"` - - `object: "thread.run"` + The object type, which is always `thread.message`. - The object type, which is always `thread.run`. + - `"thread.message"` - - `"thread.run"` + - `role: "user" or "assistant"` - - `parallel_tool_calls: boolean` + The entity that produced the message. One of `user` or `assistant`. - Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `"user"` - - `required_action: object { submit_tool_outputs, type }` + - `"assistant"` - Details on the action required to continue the run. Will be `null` if no action is required. + - `run_id: string` - - `submit_tool_outputs: object { tool_calls }` + The ID of the [run](/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. - Details on the tool outputs needed for this run to continue. + - `status: "in_progress" or "incomplete" or "completed"` - - `tool_calls: array of RequiredActionFunctionToolCall` + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - A list of the relevant tool calls. + - `"in_progress"` - - `id: string` + - `"incomplete"` - The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](/docs/api-reference/runs/submitToolOutputs) endpoint. + - `"completed"` - - `function: object { arguments, name }` + - `thread_id: string` - The function definition. + The [thread](/docs/api-reference/threads) ID that this message belongs to. - - `arguments: string` +### Example - The arguments that the model expects you to pass to the function. +```http +curl https://api.openai.com/v1/threads/$THREAD_ID/messages/$MESSAGE_ID \ + -H 'OpenAI-Beta: assistants=v2' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `name: string` +#### Response - The name of the function. +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "attachments": [ + { + "file_id": "file_id", + "tools": [ + { + "type": "code_interpreter" + } + ] + } + ], + "completed_at": 0, + "content": [ + { + "image_file": { + "file_id": "file_id", + "detail": "auto" + }, + "type": "image_file" + } + ], + "created_at": 0, + "incomplete_at": 0, + "incomplete_details": { + "reason": "content_filter" + }, + "metadata": { + "foo": "string" + }, + "object": "thread.message", + "role": "user", + "run_id": "run_id", + "status": "in_progress", + "thread_id": "thread_id" +} +``` - - `type: "function"` +### Example - The type of tool call the output is required for. For now, this is always `function`. +```http +curl https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" +``` - - `"function"` +#### Response - - `type: "submit_tool_outputs"` +```json +{ + "id": "msg_abc123", + "object": "thread.message", + "created_at": 1699017614, + "assistant_id": null, + "thread_id": "thread_abc123", + "run_id": null, + "role": "user", + "content": [ + { + "type": "text", + "text": { + "value": "How does AI work? Explain it in simple terms.", + "annotations": [] + } + } + ], + "attachments": [], + "metadata": {} +} +``` - For now, this is always `submit_tool_outputs`. +## Modify message - - `"submit_tool_outputs"` +**post** `/threads/{thread_id}/messages/{message_id}` - - `response_format: AssistantResponseFormatOption` +Modifies a message. - Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. +### Path Parameters - Setting to `{ "type": "json_schema", "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). +- `thread_id: string` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. +- `message_id: string` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. +### Body Parameters - - `"auto"` +- `metadata: optional Metadata` - `auto` is the default value + 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. - - `"auto"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `ResponseFormatText object { type }` +### Returns - Default response format. Used to generate text responses. +- `Message object { id, assistant_id, attachments, 11 more }` - - `type: "text"` + Represents a message within a [thread](/docs/api-reference/threads). - The type of response format being defined. Always `text`. + - `id: string` - - `"text"` + The identifier, which can be referenced in API endpoints. - - `ResponseFormatJSONObject object { type }` + - `assistant_id: string` - 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. + If applicable, the ID of the [assistant](/docs/api-reference/assistants) that authored this message. - - `type: "json_object"` + - `attachments: array of object { file_id, tools }` - The type of response format being defined. Always `json_object`. + A list of files attached to the message, and the tools they were added to. - - `"json_object"` + - `file_id: optional string` - - `ResponseFormatJSONSchema object { json_schema, type }` + The ID of the file to attach to the message. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + - `tools: optional array of CodeInterpreterTool or object { type }` - - `json_schema: object { name, description, schema, strict }` + The tools to add this file to. - Structured Outputs configuration options, including a JSON Schema. + - `CodeInterpreterTool object { type }` - - `name: string` + - `type: "code_interpreter"` - 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 type of tool being defined: `code_interpreter` - - `description: optional string` + - `"code_interpreter"` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `FileSearchTool object { type }` - - `schema: optional map[unknown]` + - `type: "file_search"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The type of tool being defined: `file_search` - - `strict: optional boolean` + - `"file_search"` - 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). + - `completed_at: number` - - `type: "json_schema"` + The Unix timestamp (in seconds) for when the message was completed. - The type of response format being defined. Always `json_schema`. + - `content: array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlock or RefusalContentBlock` - - `"json_schema"` + The content of the message in array of text and/or images. - - `started_at: number` + - `ImageFileContentBlock object { image_file, type }` - The Unix timestamp (in seconds) for when the run was started. + References an image [File](/docs/api-reference/files) in the content of a message. - - `status: "queued" or "in_progress" or "requires_action" or 6 more` + - `image_file: ImageFile` - The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + - `file_id: string` - - `"queued"` + The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `"in_progress"` + - `detail: optional "auto" or "low" or "high"` - - `"requires_action"` + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `"cancelling"` + - `"auto"` - - `"cancelled"` + - `"low"` - - `"failed"` + - `"high"` - - `"completed"` + - `type: "image_file"` - - `"incomplete"` + Always `image_file`. - - `"expired"` + - `"image_file"` - - `thread_id: string` + - `ImageURLContentBlock object { image_url, type }` - The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. + References an image URL in the content of a message. - - `tool_choice: AssistantToolChoiceOption` + - `image_url: ImageURL` - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + - `url: string` - - `"none" or "auto" or "required"` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. + - `detail: optional "auto" or "low" or "high"` - - `"none"` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - `"auto"` - - `"required"` + - `"low"` - - `AssistantToolChoice object { type, function }` + - `"high"` - Specifies a tool the model should use. Use to force the model to call a specific tool. + - `type: "image_url"` - - `type: "function" or "code_interpreter" or "file_search"` + The type of the content part. - The type of the tool. If type is `function`, the function name must be set + - `"image_url"` - - `"function"` + - `TextContentBlock object { text, type }` - - `"code_interpreter"` + The text content that is part of a message. - - `"file_search"` + - `text: Text` - - `function: optional AssistantToolChoiceFunction` + - `annotations: array of FileCitationAnnotation or FilePathAnnotation` - - `name: string` + - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` - The name of the function to call. + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` + - `end_index: number` - The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. + - `file_citation: object { file_id }` - - `CodeInterpreterTool object { type }` + - `file_id: string` - - `type: "code_interpreter"` + The ID of the specific File the citation is from. - The type of tool being defined: `code_interpreter` + - `start_index: number` - - `"code_interpreter"` + - `text: string` - - `FileSearchTool object { type, file_search }` + The text in the message content that needs to be replaced. - - `type: "file_search"` + - `type: "file_citation"` - The type of tool being defined: `file_search` + Always `file_citation`. - - `"file_search"` + - `"file_citation"` - - `file_search: optional object { max_num_results, ranking_options }` + - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` - Overrides for the file search tool. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `max_num_results: optional number` + - `end_index: number` - The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + - `file_path: object { file_id }` - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `file_id: string` - - `ranking_options: optional object { score_threshold, ranker }` + The ID of the file that was generated. - The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + - `start_index: number` - See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `text: string` - - `score_threshold: number` + The text in the message content that needs to be replaced. + + - `type: "file_path"` + + Always `file_path`. + + - `"file_path"` + + - `value: string` + + The data that makes up the text. + + - `type: "text"` + + Always `text`. - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `"text"` - - `ranker: optional "auto" or "default_2024_08_21"` + - `RefusalContentBlock object { refusal, type }` - The ranker to use for the file search. If not specified will use the `auto` ranker. + The refusal content generated by the assistant. - - `"auto"` + - `refusal: string` - - `"default_2024_08_21"` + - `type: "refusal"` - - `FunctionTool object { function, type }` + Always `refusal`. - - `function: FunctionDefinition` + - `"refusal"` - - `name: string` + - `created_at: number` - The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + The Unix timestamp (in seconds) for when the message was created. - - `description: optional string` + - `incomplete_at: number` - A description of what the function does, used by the model to choose when and how to call the function. + The Unix timestamp (in seconds) for when the message was marked as incomplete. - - `parameters: optional FunctionParameters` + - `incomplete_details: object { reason }` - The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + On an incomplete message, details about why the message is incomplete. - Omitting `parameters` defines a function with an empty parameter list. + - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` - - `strict: optional boolean` + The reason the message is incomplete. - Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-calling). + - `"content_filter"` - - `type: "function"` + - `"max_tokens"` - The type of tool being defined: `function` + - `"run_cancelled"` - - `"function"` + - `"run_expired"` - - `truncation_strategy: object { type, last_messages }` + - `"run_failed"` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `metadata: Metadata` - - `type: "auto" or "last_messages"` + 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 truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `"auto"` + - `object: "thread.message"` - - `"last_messages"` + The object type, which is always `thread.message`. - - `last_messages: optional number` + - `"thread.message"` - The number of most recent messages from the thread when constructing the context for the run. + - `role: "user" or "assistant"` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + The entity that produced the message. One of `user` or `assistant`. - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + - `"user"` - - `completion_tokens: number` + - `"assistant"` - Number of completion tokens used over the course of the run. + - `run_id: string` - - `prompt_tokens: number` + The ID of the [run](/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. - Number of prompt tokens used over the course of the run. + - `status: "in_progress" or "incomplete" or "completed"` - - `total_tokens: number` + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - Total number of tokens used (prompt + completion). + - `"in_progress"` - - `temperature: optional number` + - `"incomplete"` - The sampling temperature used for this run. If not set, defaults to 1. + - `"completed"` - - `top_p: optional number` + - `thread_id: string` - The nucleus sampling value used for this run. If not set, defaults to 1. + The [thread](/docs/api-reference/threads) ID that this message belongs to. ### Example ```http -curl https://api.openai.com/v1/threads/$THREAD_ID/runs \ +curl https://api.openai.com/v1/threads/$THREAD_ID/messages/$MESSAGE_ID \ -H 'Content-Type: application/json' \ -H 'OpenAI-Beta: assistants=v2' \ -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "assistant_id": "assistant_id", - "temperature": 1, - "top_p": 1 - }' + -d '{}' ``` #### Response @@ -226777,75 +226781,54 @@ curl https://api.openai.com/v1/threads/$THREAD_ID/runs \ { "id": "id", "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expires_at": 0, - "failed_at": 0, - "incomplete_details": { - "reason": "max_completion_tokens" - }, - "instructions": "instructions", - "last_error": { - "code": "server_error", - "message": "message" - }, - "max_completion_tokens": 256, - "max_prompt_tokens": 256, - "metadata": { - "foo": "string" - }, - "model": "model", - "object": "thread.run", - "parallel_tool_calls": true, - "required_action": { - "submit_tool_outputs": { - "tool_calls": [ + "attachments": [ { - "id": "id", - "function": { - "arguments": "arguments", - "name": "name" - }, - "type": "function" - } - ] - }, - "type": "submit_tool_outputs" - }, - "response_format": "auto", - "started_at": 0, - "status": "queued", - "thread_id": "thread_id", - "tool_choice": "none", + "file_id": "file_id", "tools": [ { "type": "code_interpreter" } + ] + } ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 + "completed_at": 0, + "content": [ + { + "image_file": { + "file_id": "file_id", + "detail": "auto" }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 + "type": "image_file" + } + ], + "created_at": 0, + "incomplete_at": 0, + "incomplete_details": { + "reason": "content_filter" }, - "temperature": 0, - "top_p": 0 + "metadata": { + "foo": "string" + }, + "object": "thread.message", + "role": "user", + "run_id": "run_id", + "status": "in_progress", + "thread_id": "thread_id" } ``` ### Example ```http -curl https://api.openai.com/v1/threads/thread_abc123/runs \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ +curl https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 \ -H "Content-Type: application/json" \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "OpenAI-Beta: assistants=v2" \ -d '{ - "assistant_id": "asst_abc123" + "metadata": { + "modified": "true", + "user": "abc123" + } }' ``` @@ -226853,486 +226836,365 @@ curl https://api.openai.com/v1/threads/thread_abc123/runs \ ```json { - "id": "run_abc123", - "object": "thread.run", - "created_at": 1699063290, - "assistant_id": "asst_abc123", + "id": "msg_abc123", + "object": "thread.message", + "created_at": 1699017614, + "assistant_id": null, "thread_id": "thread_abc123", - "status": "queued", - "started_at": 1699063290, - "expires_at": null, - "cancelled_at": null, - "failed_at": null, - "completed_at": 1699063291, - "last_error": null, - "model": "gpt-4o", - "instructions": null, - "incomplete_details": null, - "tools": [ + "run_id": null, + "role": "user", + "content": [ { - "type": "code_interpreter" + "type": "text", + "text": { + "value": "How does AI work? Explain it in simple terms.", + "annotations": [] + } } ], - "metadata": {}, - "usage": null, - "temperature": 1.0, - "top_p": 1.0, - "max_prompt_tokens": 1000, - "max_completion_tokens": 1000, - "truncation_strategy": { - "type": "auto", - "last_messages": null - }, - "response_format": "auto", - "tool_choice": "auto", - "parallel_tool_calls": true + "file_ids": [], + "metadata": { + "modified": "true", + "user": "abc123" + } } ``` -### Streaming - -```http -curl https://api.openai.com/v1/threads/thread_123/runs \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" \ - -d '{ - "assistant_id": "asst_123", - "stream": true - }' -``` - -#### Response - -```json -event: thread.run.created -data: {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710331240,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - -event: thread.run.queued -data: {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710331240,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} +## Domain Types -event: thread.run.in_progress -data: {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710330641,"expires_at":1710331240,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} +### File Citation Annotation -event: thread.run.step.created -data: {"id":"step_001","object":"thread.run.step","created_at":1710330641,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710331240,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} +- `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` -event: thread.run.step.in_progress -data: {"id":"step_001","object":"thread.run.step","created_at":1710330641,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710331240,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. -event: thread.message.created -data: {"id":"msg_001","object":"thread.message","created_at":1710330641,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} + - `end_index: number` -event: thread.message.in_progress -data: {"id":"msg_001","object":"thread.message","created_at":1710330641,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} + - `file_citation: object { file_id }` -event: thread.message.delta -data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"Hello","annotations":[]}}]}} + - `file_id: string` -... + The ID of the specific File the citation is from. -event: thread.message.delta -data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" today"}}]}} + - `start_index: number` -event: thread.message.delta -data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"?"}}]}} + - `text: string` -event: thread.message.completed -data: {"id":"msg_001","object":"thread.message","created_at":1710330641,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"completed","incomplete_details":null,"incomplete_at":null,"completed_at":1710330642,"role":"assistant","content":[{"type":"text","text":{"value":"Hello! How can I assist you today?","annotations":[]}}],"metadata":{}} + The text in the message content that needs to be replaced. -event: thread.run.step.completed -data: {"id":"step_001","object":"thread.run.step","created_at":1710330641,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"completed","cancelled_at":null,"completed_at":1710330642,"expires_at":1710331240,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31}} + - `type: "file_citation"` -event: thread.run.completed -data: {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1710330641,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1710330642,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + Always `file_citation`. -event: done -data: [DONE] -``` + - `"file_citation"` -### Streaming with Functions +### File Citation Delta Annotation -```http -curl https://api.openai.com/v1/threads/thread_abc123/runs \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" \ - -d '{ - "assistant_id": "asst_abc123", - "tools": [ - { - "type": "function", - "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"] - } - } - } - ], - "stream": true - }' -``` +- `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` -#### Response + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. -```json -event: thread.run.created -data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + - `index: number` -event: thread.run.queued -data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + The index of the annotation in the text content part. -event: thread.run.in_progress -data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710348075,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + - `type: "file_citation"` -event: thread.run.step.created -data: {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} + Always `file_citation`. -event: thread.run.step.in_progress -data: {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} + - `"file_citation"` -event: thread.message.created -data: {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} + - `end_index: optional number` -event: thread.message.in_progress -data: {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} + - `file_citation: optional object { file_id, quote }` -event: thread.message.delta -data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"Hello","annotations":[]}}]}} + - `file_id: optional string` -... + The ID of the specific File the citation is from. -event: thread.message.delta -data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" today"}}]}} + - `quote: optional string` -event: thread.message.delta -data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"?"}}]}} + The specific quote in the file. -event: thread.message.completed -data: {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"completed","incomplete_details":null,"incomplete_at":null,"completed_at":1710348077,"role":"assistant","content":[{"type":"text","text":{"value":"Hello! How can I assist you today?","annotations":[]}}],"metadata":{}} + - `start_index: optional number` -event: thread.run.step.completed -data: {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"completed","cancelled_at":null,"completed_at":1710348077,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31}} + - `text: optional string` -event: thread.run.completed -data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1710348075,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1710348077,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + The text in the message content that needs to be replaced. -event: done -data: [DONE] -``` +### File Path Annotation -## Retrieve run +- `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` -**get** `/threads/{thread_id}/runs/{run_id}` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. -Retrieves a run. + - `end_index: number` -### Path Parameters + - `file_path: object { file_id }` -- `thread_id: string` + - `file_id: string` -- `run_id: string` + The ID of the file that was generated. -### Returns + - `start_index: number` -- `Run object { id, assistant_id, cancelled_at, 24 more }` + - `text: string` - Represents an execution run on a [thread](/docs/api-reference/threads). + The text in the message content that needs to be replaced. - - `id: string` + - `type: "file_path"` - The identifier, which can be referenced in API endpoints. + Always `file_path`. - - `assistant_id: string` + - `"file_path"` - The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. +### File Path Delta Annotation - - `cancelled_at: number` +- `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` - The Unix timestamp (in seconds) for when the run was cancelled. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `completed_at: number` + - `index: number` - The Unix timestamp (in seconds) for when the run was completed. + The index of the annotation in the text content part. - - `created_at: number` + - `type: "file_path"` - The Unix timestamp (in seconds) for when the run was created. + Always `file_path`. - - `expires_at: number` + - `"file_path"` - The Unix timestamp (in seconds) for when the run will expire. + - `end_index: optional number` - - `failed_at: number` + - `file_path: optional object { file_id }` - The Unix timestamp (in seconds) for when the run failed. + - `file_id: optional string` - - `incomplete_details: object { reason }` + The ID of the file that was generated. - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `start_index: optional number` - - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` + - `text: optional string` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + The text in the message content that needs to be replaced. - - `"max_completion_tokens"` +### Image File - - `"max_prompt_tokens"` +- `ImageFile object { file_id, detail }` - - `instructions: string` + - `file_id: string` - The instructions that the [assistant](/docs/api-reference/assistants) used for this run. + The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `last_error: object { code, message }` + - `detail: optional "auto" or "low" or "high"` - The last error associated with this run. Will be `null` if there are no errors. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` + - `"auto"` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `"low"` - - `"server_error"` + - `"high"` - - `"rate_limit_exceeded"` +### Image File Content Block - - `"invalid_prompt"` +- `ImageFileContentBlock object { image_file, type }` - - `message: string` + References an image [File](/docs/api-reference/files) in the content of a message. - A human-readable description of the error. + - `image_file: ImageFile` - - `max_completion_tokens: number` + - `file_id: string` - The maximum number of completion tokens specified to have been used over the course of the run. + The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `max_prompt_tokens: number` + - `detail: optional "auto" or "low" or "high"` - The maximum number of prompt tokens specified to have been used over the course of the run. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `metadata: Metadata` + - `"auto"` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `"low"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"high"` - - `model: string` + - `type: "image_file"` - The model that the [assistant](/docs/api-reference/assistants) used for this run. + Always `image_file`. - - `object: "thread.run"` + - `"image_file"` - The object type, which is always `thread.run`. +### Image File Delta - - `"thread.run"` +- `ImageFileDelta object { detail, file_id }` - - `parallel_tool_calls: boolean` + - `detail: optional "auto" or "low" or "high"` - Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `required_action: object { submit_tool_outputs, type }` + - `"auto"` - Details on the action required to continue the run. Will be `null` if no action is required. + - `"low"` - - `submit_tool_outputs: object { tool_calls }` + - `"high"` - Details on the tool outputs needed for this run to continue. + - `file_id: optional string` - - `tool_calls: array of RequiredActionFunctionToolCall` + The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - A list of the relevant tool calls. +### Image File Delta Block - - `id: string` +- `ImageFileDeltaBlock object { index, type, image_file }` - The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](/docs/api-reference/runs/submitToolOutputs) endpoint. + References an image [File](/docs/api-reference/files) in the content of a message. - - `function: object { arguments, name }` + - `index: number` - The function definition. + The index of the content part in the message. - - `arguments: string` + - `type: "image_file"` - The arguments that the model expects you to pass to the function. + Always `image_file`. - - `name: string` + - `"image_file"` - The name of the function. + - `image_file: optional ImageFileDelta` - - `type: "function"` + - `detail: optional "auto" or "low" or "high"` - The type of tool call the output is required for. For now, this is always `function`. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `"function"` + - `"auto"` - - `type: "submit_tool_outputs"` + - `"low"` - For now, this is always `submit_tool_outputs`. + - `"high"` - - `"submit_tool_outputs"` + - `file_id: optional string` - - `response_format: AssistantResponseFormatOption` + The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. +### Image URL - Setting to `{ "type": "json_schema", "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). +- `ImageURL object { url, detail }` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + - `url: string` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `"auto"` + - `detail: optional "auto" or "low" or "high"` - `auto` is the default value + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - `"auto"` - - `ResponseFormatText object { type }` - - Default response format. Used to generate text responses. - - - `type: "text"` - - The type of response format being defined. Always `text`. - - - `"text"` - - - `ResponseFormatJSONObject object { type }` + - `"low"` - 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. + - `"high"` - - `type: "json_object"` +### Image URL Content Block - The type of response format being defined. Always `json_object`. +- `ImageURLContentBlock object { image_url, type }` - - `"json_object"` + References an image URL in the content of a message. - - `ResponseFormatJSONSchema object { json_schema, type }` + - `image_url: ImageURL` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + - `url: string` - - `json_schema: object { name, description, schema, strict }` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - Structured Outputs configuration options, including a JSON Schema. + - `detail: optional "auto" or "low" or "high"` - - `name: string` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - 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. + - `"auto"` - - `description: optional string` + - `"low"` - A description of what the response format is for, used by the model to - determine how to respond in the format. + - `"high"` - - `schema: optional map[unknown]` + - `type: "image_url"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + The type of the content part. - - `strict: optional boolean` + - `"image_url"` - 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). +### Image URL Delta - - `type: "json_schema"` +- `ImageURLDelta object { detail, url }` - The type of response format being defined. Always `json_schema`. + - `detail: optional "auto" or "low" or "high"` - - `"json_schema"` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `started_at: number` + - `"auto"` - The Unix timestamp (in seconds) for when the run was started. + - `"low"` - - `status: "queued" or "in_progress" or "requires_action" or 6 more` + - `"high"` - The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + - `url: optional string` - - `"queued"` + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `"in_progress"` +### Image URL Delta Block - - `"requires_action"` +- `ImageURLDeltaBlock object { index, type, image_url }` - - `"cancelling"` + References an image URL in the content of a message. - - `"cancelled"` + - `index: number` - - `"failed"` + The index of the content part in the message. - - `"completed"` + - `type: "image_url"` - - `"incomplete"` + Always `image_url`. - - `"expired"` + - `"image_url"` - - `thread_id: string` + - `image_url: optional ImageURLDelta` - The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. + - `detail: optional "auto" or "low" or "high"` - - `tool_choice: AssistantToolChoiceOption` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + - `"auto"` - - `"none" or "auto" or "required"` + - `"low"` - `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. + - `"high"` - - `"none"` + - `url: optional string` - - `"auto"` + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `"required"` +### Message - - `AssistantToolChoice object { type, function }` +- `Message object { id, assistant_id, attachments, 11 more }` - Specifies a tool the model should use. Use to force the model to call a specific tool. + Represents a message within a [thread](/docs/api-reference/threads). - - `type: "function" or "code_interpreter" or "file_search"` + - `id: string` - The type of the tool. If type is `function`, the function name must be set + The identifier, which can be referenced in API endpoints. - - `"function"` + - `assistant_id: string` - - `"code_interpreter"` + If applicable, the ID of the [assistant](/docs/api-reference/assistants) that authored this message. - - `"file_search"` + - `attachments: array of object { file_id, tools }` - - `function: optional AssistantToolChoiceFunction` + A list of files attached to the message, and the tools they were added to. - - `name: string` + - `file_id: optional string` - The name of the function to call. + The ID of the file to attach to the message. - - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` + - `tools: optional array of CodeInterpreterTool or object { type }` - The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. + The tools to add this file to. - `CodeInterpreterTool object { type }` @@ -227342,7 +227204,7 @@ Retrieves a run. - `"code_interpreter"` - - `FileSearchTool object { type, file_search }` + - `FileSearchTool object { type }` - `type: "file_search"` @@ -227350,1450 +227212,918 @@ Retrieves a run. - `"file_search"` - - `file_search: optional object { max_num_results, ranking_options }` - - Overrides for the file search tool. + - `completed_at: number` - - `max_num_results: optional number` + The Unix timestamp (in seconds) for when the message was completed. - The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + - `content: array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlock or RefusalContentBlock` - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + The content of the message in array of text and/or images. - - `ranking_options: optional object { score_threshold, ranker }` + - `ImageFileContentBlock object { image_file, type }` - The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + References an image [File](/docs/api-reference/files) in the content of a message. - See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `image_file: ImageFile` - - `score_threshold: number` + - `file_id: string` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `ranker: optional "auto" or "default_2024_08_21"` + - `detail: optional "auto" or "low" or "high"` - The ranker to use for the file search. If not specified will use the `auto` ranker. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - `"auto"` - - `"default_2024_08_21"` - - - `FunctionTool object { function, type }` - - - `function: FunctionDefinition` - - - `name: string` - - The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - - `description: optional string` - - A description of what the function does, used by the model to choose when and how to call the function. - - - `parameters: optional FunctionParameters` + - `"low"` - The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + - `"high"` - Omitting `parameters` defines a function with an empty parameter list. + - `type: "image_file"` - - `strict: optional boolean` + Always `image_file`. - Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-calling). + - `"image_file"` - - `type: "function"` + - `ImageURLContentBlock object { image_url, type }` - The type of tool being defined: `function` + References an image URL in the content of a message. - - `"function"` + - `image_url: ImageURL` - - `truncation_strategy: object { type, last_messages }` + - `url: string` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - - `type: "auto" or "last_messages"` + - `detail: optional "auto" or "low" or "high"` - The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - `"auto"` - - `"last_messages"` + - `"low"` - - `last_messages: optional number` + - `"high"` - The number of most recent messages from the thread when constructing the context for the run. + - `type: "image_url"` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + The type of the content part. - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + - `"image_url"` - - `completion_tokens: number` + - `TextContentBlock object { text, type }` - Number of completion tokens used over the course of the run. + The text content that is part of a message. - - `prompt_tokens: number` + - `text: Text` - Number of prompt tokens used over the course of the run. + - `annotations: array of FileCitationAnnotation or FilePathAnnotation` - - `total_tokens: number` + - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` - Total number of tokens used (prompt + completion). + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `temperature: optional number` + - `end_index: number` - The sampling temperature used for this run. If not set, defaults to 1. + - `file_citation: object { file_id }` - - `top_p: optional number` + - `file_id: string` - The nucleus sampling value used for this run. If not set, defaults to 1. + The ID of the specific File the citation is from. -### Example + - `start_index: number` -```http -curl https://api.openai.com/v1/threads/$THREAD_ID/runs/$RUN_ID \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `text: string` -#### Response + The text in the message content that needs to be replaced. -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expires_at": 0, - "failed_at": 0, - "incomplete_details": { - "reason": "max_completion_tokens" - }, - "instructions": "instructions", - "last_error": { - "code": "server_error", - "message": "message" - }, - "max_completion_tokens": 256, - "max_prompt_tokens": 256, - "metadata": { - "foo": "string" - }, - "model": "model", - "object": "thread.run", - "parallel_tool_calls": true, - "required_action": { - "submit_tool_outputs": { - "tool_calls": [ - { - "id": "id", - "function": { - "arguments": "arguments", - "name": "name" - }, - "type": "function" - } - ] - }, - "type": "submit_tool_outputs" - }, - "response_format": "auto", - "started_at": 0, - "status": "queued", - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - { - "type": "code_interpreter" - } - ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - }, - "temperature": 0, - "top_p": 0 -} -``` + - `type: "file_citation"` -### Example + Always `file_citation`. -```http -curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: assistants=v2" -``` + - `"file_citation"` -#### Response + - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` -```json -{ - "id": "run_abc123", - "object": "thread.run", - "created_at": 1699075072, - "assistant_id": "asst_abc123", - "thread_id": "thread_abc123", - "status": "completed", - "started_at": 1699075072, - "expires_at": null, - "cancelled_at": null, - "failed_at": null, - "completed_at": 1699075073, - "last_error": null, - "model": "gpt-4o", - "instructions": null, - "incomplete_details": null, - "tools": [ - { - "type": "code_interpreter" - } - ], - "metadata": {}, - "usage": { - "prompt_tokens": 123, - "completion_tokens": 456, - "total_tokens": 579 - }, - "temperature": 1.0, - "top_p": 1.0, - "max_prompt_tokens": 1000, - "max_completion_tokens": 1000, - "truncation_strategy": { - "type": "auto", - "last_messages": null - }, - "response_format": "auto", - "tool_choice": "auto", - "parallel_tool_calls": true -} -``` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. -## Modify run + - `end_index: number` -**post** `/threads/{thread_id}/runs/{run_id}` + - `file_path: object { file_id }` -Modifies a run. + - `file_id: string` -### Path Parameters + The ID of the file that was generated. -- `thread_id: string` + - `start_index: number` -- `run_id: string` + - `text: string` -### Body Parameters + The text in the message content that needs to be replaced. -- `metadata: optional Metadata` + - `type: "file_path"` - 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. + Always `file_path`. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"file_path"` -### Returns + - `value: string` -- `Run object { id, assistant_id, cancelled_at, 24 more }` + The data that makes up the text. - Represents an execution run on a [thread](/docs/api-reference/threads). + - `type: "text"` - - `id: string` + Always `text`. - The identifier, which can be referenced in API endpoints. + - `"text"` - - `assistant_id: string` + - `RefusalContentBlock object { refusal, type }` - The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. + The refusal content generated by the assistant. - - `cancelled_at: number` + - `refusal: string` - The Unix timestamp (in seconds) for when the run was cancelled. + - `type: "refusal"` - - `completed_at: number` + Always `refusal`. - The Unix timestamp (in seconds) for when the run was completed. + - `"refusal"` - `created_at: number` - The Unix timestamp (in seconds) for when the run was created. - - - `expires_at: number` - - The Unix timestamp (in seconds) for when the run will expire. + The Unix timestamp (in seconds) for when the message was created. - - `failed_at: number` + - `incomplete_at: number` - The Unix timestamp (in seconds) for when the run failed. + The Unix timestamp (in seconds) for when the message was marked as incomplete. - `incomplete_details: object { reason }` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` - - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - - `"max_completion_tokens"` - - - `"max_prompt_tokens"` - - - `instructions: string` - - The instructions that the [assistant](/docs/api-reference/assistants) used for this run. - - - `last_error: object { code, message }` - - The last error associated with this run. Will be `null` if there are no errors. - - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` - - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - - `"server_error"` - - - `"rate_limit_exceeded"` + On an incomplete message, details about why the message is incomplete. - - `"invalid_prompt"` + - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` - - `message: string` + The reason the message is incomplete. - A human-readable description of the error. + - `"content_filter"` - - `max_completion_tokens: number` + - `"max_tokens"` - The maximum number of completion tokens specified to have been used over the course of the run. + - `"run_cancelled"` - - `max_prompt_tokens: number` + - `"run_expired"` - The maximum number of prompt tokens specified to have been used over the course of the run. + - `"run_failed"` - `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: string` - - The model that the [assistant](/docs/api-reference/assistants) used for this run. - - - `object: "thread.run"` - - The object type, which is always `thread.run`. - - - `"thread.run"` - - - `parallel_tool_calls: boolean` - - Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - - `required_action: object { submit_tool_outputs, type }` - - Details on the action required to continue the run. Will be `null` if no action is required. - - - `submit_tool_outputs: object { tool_calls }` - - Details on the tool outputs needed for this run to continue. - - - `tool_calls: array of RequiredActionFunctionToolCall` - - A list of the relevant tool calls. - - - `id: string` - - The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](/docs/api-reference/runs/submitToolOutputs) endpoint. - - - `function: object { arguments, name }` - - The function definition. - - - `arguments: string` - - The arguments that the model expects you to pass to the function. - - - `name: string` - - The name of the function. + useful for storing additional information about the object in a structured + format, and querying for objects via API or the dashboard. - - `type: "function"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The type of tool call the output is required for. For now, this is always `function`. + - `object: "thread.message"` - - `"function"` + The object type, which is always `thread.message`. - - `type: "submit_tool_outputs"` + - `"thread.message"` - For now, this is always `submit_tool_outputs`. + - `role: "user" or "assistant"` - - `"submit_tool_outputs"` + The entity that produced the message. One of `user` or `assistant`. - - `response_format: AssistantResponseFormatOption` + - `"user"` - Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `"assistant"` - Setting to `{ "type": "json_schema", "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). + - `run_id: string` - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. + The ID of the [run](/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `status: "in_progress" or "incomplete" or "completed"` - - `"auto"` + The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. - `auto` is the default value + - `"in_progress"` - - `"auto"` + - `"incomplete"` - - `ResponseFormatText object { type }` + - `"completed"` - Default response format. Used to generate text responses. + - `thread_id: string` - - `type: "text"` + The [thread](/docs/api-reference/threads) ID that this message belongs to. - The type of response format being defined. Always `text`. +### Message Deleted - - `"text"` +- `MessageDeleted object { id, deleted, object }` - - `ResponseFormatJSONObject object { type }` + - `id: string` - 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. + - `deleted: boolean` - - `type: "json_object"` + - `object: "thread.message.deleted"` - The type of response format being defined. Always `json_object`. + - `"thread.message.deleted"` - - `"json_object"` +### Message Delta - - `ResponseFormatJSONSchema object { json_schema, type }` +- `MessageDelta object { content, role }` - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + The delta containing the fields that have changed on the Message. - - `json_schema: object { name, description, schema, strict }` + - `content: optional array of ImageFileDeltaBlock or TextDeltaBlock or RefusalDeltaBlock or ImageURLDeltaBlock` - Structured Outputs configuration options, including a JSON Schema. + The content of the message in array of text and/or images. - - `name: string` + - `ImageFileDeltaBlock object { index, type, image_file }` - 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. + References an image [File](/docs/api-reference/files) in the content of a message. - - `description: optional string` + - `index: number` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The index of the content part in the message. - - `schema: optional map[unknown]` + - `type: "image_file"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + Always `image_file`. - - `strict: optional boolean` + - `"image_file"` - 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). + - `image_file: optional ImageFileDelta` - - `type: "json_schema"` + - `detail: optional "auto" or "low" or "high"` - The type of response format being defined. Always `json_schema`. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `"json_schema"` + - `"auto"` - - `started_at: number` + - `"low"` - The Unix timestamp (in seconds) for when the run was started. + - `"high"` - - `status: "queued" or "in_progress" or "requires_action" or 6 more` + - `file_id: optional string` - The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `"queued"` + - `TextDeltaBlock object { index, type, text }` - - `"in_progress"` + The text content that is part of a message. - - `"requires_action"` + - `index: number` - - `"cancelling"` + The index of the content part in the message. - - `"cancelled"` + - `type: "text"` - - `"failed"` + Always `text`. - - `"completed"` + - `"text"` - - `"incomplete"` + - `text: optional TextDelta` - - `"expired"` + - `annotations: optional array of FileCitationDeltaAnnotation or FilePathDeltaAnnotation` - - `thread_id: string` + - `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` - The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `tool_choice: AssistantToolChoiceOption` + - `index: number` - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + The index of the annotation in the text content part. - - `"none" or "auto" or "required"` + - `type: "file_citation"` - `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. + Always `file_citation`. - - `"none"` + - `"file_citation"` - - `"auto"` + - `end_index: optional number` - - `"required"` + - `file_citation: optional object { file_id, quote }` - - `AssistantToolChoice object { type, function }` + - `file_id: optional string` - Specifies a tool the model should use. Use to force the model to call a specific tool. + The ID of the specific File the citation is from. - - `type: "function" or "code_interpreter" or "file_search"` + - `quote: optional string` - The type of the tool. If type is `function`, the function name must be set + The specific quote in the file. - - `"function"` + - `start_index: optional number` - - `"code_interpreter"` + - `text: optional string` - - `"file_search"` + The text in the message content that needs to be replaced. - - `function: optional AssistantToolChoiceFunction` + - `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` - - `name: string` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - The name of the function to call. + - `index: number` - - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` + The index of the annotation in the text content part. - The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. + - `type: "file_path"` - - `CodeInterpreterTool object { type }` + Always `file_path`. - - `type: "code_interpreter"` + - `"file_path"` - The type of tool being defined: `code_interpreter` + - `end_index: optional number` - - `"code_interpreter"` + - `file_path: optional object { file_id }` - - `FileSearchTool object { type, file_search }` + - `file_id: optional string` - - `type: "file_search"` + The ID of the file that was generated. - The type of tool being defined: `file_search` + - `start_index: optional number` - - `"file_search"` + - `text: optional string` - - `file_search: optional object { max_num_results, ranking_options }` + The text in the message content that needs to be replaced. - Overrides for the file search tool. + - `value: optional string` - - `max_num_results: optional number` + The data that makes up the text. - The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + - `RefusalDeltaBlock object { index, type, refusal }` - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + The refusal content that is part of a message. - - `ranking_options: optional object { score_threshold, ranker }` + - `index: number` - The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + The index of the refusal part in the message. - See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `type: "refusal"` - - `score_threshold: number` + Always `refusal`. - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `"refusal"` - - `ranker: optional "auto" or "default_2024_08_21"` + - `refusal: optional string` - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `ImageURLDeltaBlock object { index, type, image_url }` - - `"auto"` + References an image URL in the content of a message. - - `"default_2024_08_21"` + - `index: number` - - `FunctionTool object { function, type }` + The index of the content part in the message. - - `function: FunctionDefinition` + - `type: "image_url"` - - `name: string` + Always `image_url`. - The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + - `"image_url"` - - `description: optional string` + - `image_url: optional ImageURLDelta` - A description of what the function does, used by the model to choose when and how to call the function. + - `detail: optional "auto" or "low" or "high"` - - `parameters: optional FunctionParameters` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + - `"auto"` - Omitting `parameters` defines a function with an empty parameter list. + - `"low"` - - `strict: optional boolean` + - `"high"` - Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-calling). + - `url: optional string` - - `type: "function"` + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The type of tool being defined: `function` + - `role: optional "user" or "assistant"` - - `"function"` + The entity that produced the message. One of `user` or `assistant`. - - `truncation_strategy: object { type, last_messages }` + - `"user"` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `"assistant"` - - `type: "auto" or "last_messages"` +### Message Delta Event - The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. +- `MessageDeltaEvent object { id, delta, object }` - - `"auto"` + Represents a message delta i.e. any changed fields on a message during streaming. - - `"last_messages"` + - `id: string` - - `last_messages: optional number` + The identifier of the message, which can be referenced in API endpoints. - The number of most recent messages from the thread when constructing the context for the run. + - `delta: MessageDelta` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + The delta containing the fields that have changed on the Message. - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + - `content: optional array of ImageFileDeltaBlock or TextDeltaBlock or RefusalDeltaBlock or ImageURLDeltaBlock` - - `completion_tokens: number` + The content of the message in array of text and/or images. - Number of completion tokens used over the course of the run. + - `ImageFileDeltaBlock object { index, type, image_file }` - - `prompt_tokens: number` + References an image [File](/docs/api-reference/files) in the content of a message. - Number of prompt tokens used over the course of the run. + - `index: number` - - `total_tokens: number` + The index of the content part in the message. - Total number of tokens used (prompt + completion). + - `type: "image_file"` - - `temperature: optional number` + Always `image_file`. - The sampling temperature used for this run. If not set, defaults to 1. + - `"image_file"` - - `top_p: optional number` + - `image_file: optional ImageFileDelta` - The nucleus sampling value used for this run. If not set, defaults to 1. + - `detail: optional "auto" or "low" or "high"` -### Example + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. -```http -curl https://api.openai.com/v1/threads/$THREAD_ID/runs/$RUN_ID \ - -H 'Content-Type: application/json' \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{}' -``` + - `"auto"` -#### Response + - `"low"` -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expires_at": 0, - "failed_at": 0, - "incomplete_details": { - "reason": "max_completion_tokens" - }, - "instructions": "instructions", - "last_error": { - "code": "server_error", - "message": "message" - }, - "max_completion_tokens": 256, - "max_prompt_tokens": 256, - "metadata": { - "foo": "string" - }, - "model": "model", - "object": "thread.run", - "parallel_tool_calls": true, - "required_action": { - "submit_tool_outputs": { - "tool_calls": [ - { - "id": "id", - "function": { - "arguments": "arguments", - "name": "name" - }, - "type": "function" - } - ] - }, - "type": "submit_tool_outputs" - }, - "response_format": "auto", - "started_at": 0, - "status": "queued", - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - { - "type": "code_interpreter" - } - ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - }, - "temperature": 0, - "top_p": 0 -} -``` + - `"high"` -### Example + - `file_id: optional string` -```http -curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" \ - -d '{ - "metadata": { - "user_id": "user_abc123" - } - }' -``` + The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. -#### Response + - `TextDeltaBlock object { index, type, text }` -```json -{ - "id": "run_abc123", - "object": "thread.run", - "created_at": 1699075072, - "assistant_id": "asst_abc123", - "thread_id": "thread_abc123", - "status": "completed", - "started_at": 1699075072, - "expires_at": null, - "cancelled_at": null, - "failed_at": null, - "completed_at": 1699075073, - "last_error": null, - "model": "gpt-4o", - "instructions": null, - "incomplete_details": null, - "tools": [ - { - "type": "code_interpreter" - } - ], - "tool_resources": { - "code_interpreter": { - "file_ids": [ - "file-abc123", - "file-abc456" - ] - } - }, - "metadata": { - "user_id": "user_abc123" - }, - "usage": { - "prompt_tokens": 123, - "completion_tokens": 456, - "total_tokens": 579 - }, - "temperature": 1.0, - "top_p": 1.0, - "max_prompt_tokens": 1000, - "max_completion_tokens": 1000, - "truncation_strategy": { - "type": "auto", - "last_messages": null - }, - "response_format": "auto", - "tool_choice": "auto", - "parallel_tool_calls": true -} -``` + The text content that is part of a message. -## Submit tool outputs to run + - `index: number` -**post** `/threads/{thread_id}/runs/{run_id}/submit_tool_outputs` + The index of the content part in the message. -When a run has the `status: "requires_action"` and `required_action.type` is `submit_tool_outputs`, this endpoint can be used to submit the outputs from the tool calls once they're all completed. All outputs must be submitted in a single request. + - `type: "text"` -### Path Parameters + Always `text`. -- `thread_id: string` + - `"text"` -- `run_id: string` + - `text: optional TextDelta` -### Body Parameters + - `annotations: optional array of FileCitationDeltaAnnotation or FilePathDeltaAnnotation` -- `tool_outputs: array of object { output, tool_call_id }` + - `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` - A list of tools for which the outputs are being submitted. + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `output: optional string` + - `index: number` - The output of the tool call to be submitted to continue the run. + The index of the annotation in the text content part. - - `tool_call_id: optional string` + - `type: "file_citation"` - The ID of the tool call in the `required_action` object within the run object the output is being submitted for. + Always `file_citation`. -- `stream: optional boolean` + - `"file_citation"` - If `true`, returns a stream of events that happen during the Run as server-sent events, terminating when the Run enters a terminal state with a `data: [DONE]` message. + - `end_index: optional number` -### Returns + - `file_citation: optional object { file_id, quote }` -- `Run object { id, assistant_id, cancelled_at, 24 more }` + - `file_id: optional string` - Represents an execution run on a [thread](/docs/api-reference/threads). + The ID of the specific File the citation is from. - - `id: string` + - `quote: optional string` - The identifier, which can be referenced in API endpoints. + The specific quote in the file. - - `assistant_id: string` + - `start_index: optional number` - The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. + - `text: optional string` - - `cancelled_at: number` + The text in the message content that needs to be replaced. - The Unix timestamp (in seconds) for when the run was cancelled. + - `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` - - `completed_at: number` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - The Unix timestamp (in seconds) for when the run was completed. + - `index: number` - - `created_at: number` + The index of the annotation in the text content part. - The Unix timestamp (in seconds) for when the run was created. + - `type: "file_path"` - - `expires_at: number` + Always `file_path`. - The Unix timestamp (in seconds) for when the run will expire. + - `"file_path"` - - `failed_at: number` + - `end_index: optional number` - The Unix timestamp (in seconds) for when the run failed. + - `file_path: optional object { file_id }` - - `incomplete_details: object { reason }` + - `file_id: optional string` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + The ID of the file that was generated. - - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` + - `start_index: optional number` - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `text: optional string` - - `"max_completion_tokens"` + The text in the message content that needs to be replaced. - - `"max_prompt_tokens"` + - `value: optional string` - - `instructions: string` + The data that makes up the text. - The instructions that the [assistant](/docs/api-reference/assistants) used for this run. + - `RefusalDeltaBlock object { index, type, refusal }` - - `last_error: object { code, message }` + The refusal content that is part of a message. - The last error associated with this run. Will be `null` if there are no errors. + - `index: number` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` + The index of the refusal part in the message. - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `type: "refusal"` - - `"server_error"` + Always `refusal`. - - `"rate_limit_exceeded"` + - `"refusal"` - - `"invalid_prompt"` + - `refusal: optional string` - - `message: string` + - `ImageURLDeltaBlock object { index, type, image_url }` - A human-readable description of the error. + References an image URL in the content of a message. - - `max_completion_tokens: number` + - `index: number` - The maximum number of completion tokens specified to have been used over the course of the run. + The index of the content part in the message. - - `max_prompt_tokens: number` + - `type: "image_url"` - The maximum number of prompt tokens specified to have been used over the course of the run. + Always `image_url`. - - `metadata: Metadata` + - `"image_url"` - 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. + - `image_url: optional ImageURLDelta` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `detail: optional "auto" or "low" or "high"` - - `model: string` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. - The model that the [assistant](/docs/api-reference/assistants) used for this run. + - `"auto"` - - `object: "thread.run"` + - `"low"` - The object type, which is always `thread.run`. + - `"high"` - - `"thread.run"` + - `url: optional string` - - `parallel_tool_calls: boolean` + The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + - `role: optional "user" or "assistant"` - - `required_action: object { submit_tool_outputs, type }` + The entity that produced the message. One of `user` or `assistant`. - Details on the action required to continue the run. Will be `null` if no action is required. + - `"user"` - - `submit_tool_outputs: object { tool_calls }` + - `"assistant"` - Details on the tool outputs needed for this run to continue. + - `object: "thread.message.delta"` - - `tool_calls: array of RequiredActionFunctionToolCall` + The object type, which is always `thread.message.delta`. - A list of the relevant tool calls. + - `"thread.message.delta"` - - `id: string` +### Refusal Content Block - The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](/docs/api-reference/runs/submitToolOutputs) endpoint. +- `RefusalContentBlock object { refusal, type }` - - `function: object { arguments, name }` + The refusal content generated by the assistant. - The function definition. + - `refusal: string` - - `arguments: string` + - `type: "refusal"` - The arguments that the model expects you to pass to the function. + Always `refusal`. - - `name: string` + - `"refusal"` - The name of the function. +### Refusal Delta Block - - `type: "function"` +- `RefusalDeltaBlock object { index, type, refusal }` - The type of tool call the output is required for. For now, this is always `function`. + The refusal content that is part of a message. - - `"function"` + - `index: number` - - `type: "submit_tool_outputs"` + The index of the refusal part in the message. - For now, this is always `submit_tool_outputs`. + - `type: "refusal"` - - `"submit_tool_outputs"` + Always `refusal`. - - `response_format: AssistantResponseFormatOption` + - `"refusal"` - Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. + - `refusal: optional string` - Setting to `{ "type": "json_schema", "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). +### Text - Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. +- `Text object { annotations, value }` - **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. + - `annotations: array of FileCitationAnnotation or FilePathAnnotation` - - `"auto"` + - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` - `auto` is the default value + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `"auto"` + - `end_index: number` - - `ResponseFormatText object { type }` + - `file_citation: object { file_id }` - Default response format. Used to generate text responses. + - `file_id: string` - - `type: "text"` + The ID of the specific File the citation is from. - The type of response format being defined. Always `text`. + - `start_index: number` - - `"text"` + - `text: string` - - `ResponseFormatJSONObject object { type }` + The text in the message content that needs to be replaced. - 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: "file_citation"` - - `type: "json_object"` + Always `file_citation`. - The type of response format being defined. Always `json_object`. + - `"file_citation"` - - `"json_object"` + - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` - - `ResponseFormatJSONSchema object { json_schema, type }` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - JSON Schema response format. Used to generate structured JSON responses. - Learn more about [Structured Outputs](/docs/guides/structured-outputs). + - `end_index: number` - - `json_schema: object { name, description, schema, strict }` + - `file_path: object { file_id }` - Structured Outputs configuration options, including a JSON Schema. + - `file_id: string` - - `name: string` + The ID of the file that was generated. - 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. + - `start_index: number` - - `description: optional string` + - `text: string` - A description of what the response format is for, used by the model to - determine how to respond in the format. + The text in the message content that needs to be replaced. - - `schema: optional map[unknown]` + - `type: "file_path"` - The schema for the response format, described as a JSON Schema object. - Learn how to build JSON schemas [here](https://json-schema.org/). + Always `file_path`. - - `strict: optional boolean` + - `"file_path"` - 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). + - `value: string` - - `type: "json_schema"` + The data that makes up the text. - The type of response format being defined. Always `json_schema`. +### Text Content Block - - `"json_schema"` +- `TextContentBlock object { text, type }` - - `started_at: number` + The text content that is part of a message. - The Unix timestamp (in seconds) for when the run was started. + - `text: Text` - - `status: "queued" or "in_progress" or "requires_action" or 6 more` + - `annotations: array of FileCitationAnnotation or FilePathAnnotation` - The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` - - `"queued"` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - `"in_progress"` + - `end_index: number` - - `"requires_action"` + - `file_citation: object { file_id }` - - `"cancelling"` + - `file_id: string` - - `"cancelled"` + The ID of the specific File the citation is from. - - `"failed"` + - `start_index: number` - - `"completed"` + - `text: string` - - `"incomplete"` + The text in the message content that needs to be replaced. - - `"expired"` + - `type: "file_citation"` - - `thread_id: string` + Always `file_citation`. - The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. + - `"file_citation"` - - `tool_choice: AssistantToolChoiceOption` + - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` - Controls which (if any) tool is called by the model. - `none` means the model will not call any tools and instead generates a message. - `auto` is the default value and means the model can pick between generating a message or calling one or more tools. - `required` means the model must call one or more tools before responding to the user. - Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - `"none" or "auto" or "required"` + - `end_index: number` - `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. + - `file_path: object { file_id }` - - `"none"` + - `file_id: string` - - `"auto"` + The ID of the file that was generated. - - `"required"` + - `start_index: number` - - `AssistantToolChoice object { type, function }` + - `text: string` - Specifies a tool the model should use. Use to force the model to call a specific tool. + The text in the message content that needs to be replaced. - - `type: "function" or "code_interpreter" or "file_search"` + - `type: "file_path"` - The type of the tool. If type is `function`, the function name must be set + Always `file_path`. - - `"function"` + - `"file_path"` - - `"code_interpreter"` + - `value: string` - - `"file_search"` + The data that makes up the text. - - `function: optional AssistantToolChoiceFunction` + - `type: "text"` - - `name: string` + Always `text`. - The name of the function to call. + - `"text"` - - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` +### Text Content Block Param - The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. +- `TextContentBlockParam object { text, type }` - - `CodeInterpreterTool object { type }` + The text content that is part of a message. - - `type: "code_interpreter"` + - `text: string` - The type of tool being defined: `code_interpreter` + Text content to be sent to the model - - `"code_interpreter"` + - `type: "text"` - - `FileSearchTool object { type, file_search }` + Always `text`. - - `type: "file_search"` + - `"text"` - The type of tool being defined: `file_search` +### Text Delta - - `"file_search"` +- `TextDelta object { annotations, value }` - - `file_search: optional object { max_num_results, ranking_options }` + - `annotations: optional array of FileCitationDeltaAnnotation or FilePathDeltaAnnotation` - Overrides for the file search tool. + - `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` - - `max_num_results: optional number` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. + - `index: number` - Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + The index of the annotation in the text content part. - - `ranking_options: optional object { score_threshold, ranker }` + - `type: "file_citation"` - The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + Always `file_citation`. - See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + - `"file_citation"` - - `score_threshold: number` + - `end_index: optional number` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `file_citation: optional object { file_id, quote }` - - `ranker: optional "auto" or "default_2024_08_21"` + - `file_id: optional string` - The ranker to use for the file search. If not specified will use the `auto` ranker. + The ID of the specific File the citation is from. - - `"auto"` + - `quote: optional string` - - `"default_2024_08_21"` + The specific quote in the file. - - `FunctionTool object { function, type }` + - `start_index: optional number` - - `function: FunctionDefinition` + - `text: optional string` - - `name: string` + The text in the message content that needs to be replaced. - The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. + - `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` - - `description: optional string` + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - A description of what the function does, used by the model to choose when and how to call the function. + - `index: number` - - `parameters: optional FunctionParameters` + The index of the annotation in the text content part. - The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + - `type: "file_path"` - Omitting `parameters` defines a function with an empty parameter list. + Always `file_path`. - - `strict: optional boolean` + - `"file_path"` - Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-calling). + - `end_index: optional number` - - `type: "function"` + - `file_path: optional object { file_id }` - The type of tool being defined: `function` + - `file_id: optional string` - - `"function"` + The ID of the file that was generated. - - `truncation_strategy: object { type, last_messages }` + - `start_index: optional number` - Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. + - `text: optional string` - - `type: "auto" or "last_messages"` + The text in the message content that needs to be replaced. - The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. + - `value: optional string` - - `"auto"` + The data that makes up the text. - - `"last_messages"` +### Text Delta Block - - `last_messages: optional number` +- `TextDeltaBlock object { index, type, text }` - The number of most recent messages from the thread when constructing the context for the run. + The text content that is part of a message. - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `index: number` - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). + The index of the content part in the message. - - `completion_tokens: number` + - `type: "text"` - Number of completion tokens used over the course of the run. + Always `text`. - - `prompt_tokens: number` + - `"text"` - Number of prompt tokens used over the course of the run. + - `text: optional TextDelta` - - `total_tokens: number` + - `annotations: optional array of FileCitationDeltaAnnotation or FilePathDeltaAnnotation` - Total number of tokens used (prompt + completion). + - `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` - - `temperature: optional number` + A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - The sampling temperature used for this run. If not set, defaults to 1. + - `index: number` - - `top_p: optional number` + The index of the annotation in the text content part. - The nucleus sampling value used for this run. If not set, defaults to 1. + - `type: "file_citation"` -### Example + Always `file_citation`. -```http -curl https://api.openai.com/v1/threads/$THREAD_ID/runs/$RUN_ID/submit_tool_outputs \ - -H 'Content-Type: application/json' \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "tool_outputs": [ - {} - ] - }' -``` + - `"file_citation"` -#### Response + - `end_index: optional number` -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "cancelled_at": 0, - "completed_at": 0, - "created_at": 0, - "expires_at": 0, - "failed_at": 0, - "incomplete_details": { - "reason": "max_completion_tokens" - }, - "instructions": "instructions", - "last_error": { - "code": "server_error", - "message": "message" - }, - "max_completion_tokens": 256, - "max_prompt_tokens": 256, - "metadata": { - "foo": "string" - }, - "model": "model", - "object": "thread.run", - "parallel_tool_calls": true, - "required_action": { - "submit_tool_outputs": { - "tool_calls": [ - { - "id": "id", - "function": { - "arguments": "arguments", - "name": "name" - }, - "type": "function" - } - ] - }, - "type": "submit_tool_outputs" - }, - "response_format": "auto", - "started_at": 0, - "status": "queued", - "thread_id": "thread_id", - "tool_choice": "none", - "tools": [ - { - "type": "code_interpreter" - } - ], - "truncation_strategy": { - "type": "auto", - "last_messages": 1 - }, - "usage": { - "completion_tokens": 0, - "prompt_tokens": 0, - "total_tokens": 0 - }, - "temperature": 0, - "top_p": 0 -} -``` + - `file_citation: optional object { file_id, quote }` -### Example + - `file_id: optional string` -```http -curl https://api.openai.com/v1/threads/thread_123/runs/run_123/submit_tool_outputs \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" \ - -d '{ - "tool_outputs": [ - { - "tool_call_id": "call_001", - "output": "70 degrees and sunny." - } - ] - }' -``` + The ID of the specific File the citation is from. -#### Response + - `quote: optional string` -```json -{ - "id": "run_123", - "object": "thread.run", - "created_at": 1699075592, - "assistant_id": "asst_123", - "thread_id": "thread_123", - "status": "queued", - "started_at": 1699075592, - "expires_at": 1699076192, - "cancelled_at": null, - "failed_at": null, - "completed_at": null, - "last_error": null, - "model": "gpt-4o", - "instructions": null, - "tools": [ - { - "type": "function", - "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"] - } - } - } - ], - "metadata": {}, - "usage": null, - "temperature": 1.0, - "top_p": 1.0, - "max_prompt_tokens": 1000, - "max_completion_tokens": 1000, - "truncation_strategy": { - "type": "auto", - "last_messages": null - }, - "response_format": "auto", - "tool_choice": "auto", - "parallel_tool_calls": true -} -``` + The specific quote in the file. -### Streaming + - `start_index: optional number` -```http -curl https://api.openai.com/v1/threads/thread_123/runs/run_123/submit_tool_outputs \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" \ - -d '{ - "tool_outputs": [ - { - "tool_call_id": "call_001", - "output": "70 degrees and sunny." - } - ], - "stream": true - }' -``` + - `text: optional string` -#### Response + The text in the message content that needs to be replaced. -```json -event: thread.run.step.completed -data: {"id":"step_001","object":"thread.run.step","created_at":1710352449,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"tool_calls","status":"completed","cancelled_at":null,"completed_at":1710352475,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"tool_calls","tool_calls":[{"id":"call_iWr0kQ2EaYMaxNdl0v3KYkx7","type":"function","function":{"name":"get_current_weather","arguments":"{\"location\":\"San Francisco, CA\",\"unit\":\"fahrenheit\"}","output":"70 degrees and sunny."}}]},"usage":{"prompt_tokens":291,"completion_tokens":24,"total_tokens":315}} + - `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` -event: thread.run.queued -data: {"id":"run_123","object":"thread.run","created_at":1710352447,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":1710352448,"expires_at":1710353047,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","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"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. -event: thread.run.in_progress -data: {"id":"run_123","object":"thread.run","created_at":1710352447,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710352475,"expires_at":1710353047,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","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"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + - `index: number` -event: thread.run.step.created -data: {"id":"step_002","object":"thread.run.step","created_at":1710352476,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_002"}},"usage":null} + The index of the annotation in the text content part. -event: thread.run.step.in_progress -data: {"id":"step_002","object":"thread.run.step","created_at":1710352476,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_002"}},"usage":null} + - `type: "file_path"` -event: thread.message.created -data: {"id":"msg_002","object":"thread.message","created_at":1710352476,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} + Always `file_path`. -event: thread.message.in_progress -data: {"id":"msg_002","object":"thread.message","created_at":1710352476,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} + - `"file_path"` -event: thread.message.delta -data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"The","annotations":[]}}]}} + - `end_index: optional number` -event: thread.message.delta -data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" current"}}]}} + - `file_path: optional object { file_id }` -event: thread.message.delta -data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" weather"}}]}} + - `file_id: optional string` -... + The ID of the file that was generated. -event: thread.message.delta -data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" sunny"}}]}} + - `start_index: optional number` -event: thread.message.delta -data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"."}}]}} + - `text: optional string` -event: thread.message.completed -data: {"id":"msg_002","object":"thread.message","created_at":1710352476,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"completed","incomplete_details":null,"incomplete_at":null,"completed_at":1710352477,"role":"assistant","content":[{"type":"text","text":{"value":"The current weather in San Francisco, CA is 70 degrees Fahrenheit and sunny.","annotations":[]}}],"metadata":{}} + The text in the message content that needs to be replaced. -event: thread.run.step.completed -data: {"id":"step_002","object":"thread.run.step","created_at":1710352476,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"completed","cancelled_at":null,"completed_at":1710352477,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_002"}},"usage":{"prompt_tokens":329,"completion_tokens":18,"total_tokens":347}} + - `value: optional string` -event: thread.run.completed -data: {"id":"run_123","object":"thread.run","created_at":1710352447,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1710352475,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1710352477,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","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"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + The data that makes up the text. -event: done -data: [DONE] -``` +# Runs ## Cancel a run @@ -229329,113 +228659,158 @@ curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/cancel \ } ``` -## Domain Types +## Create run -### Required Action Function Tool Call +**post** `/threads/{thread_id}/runs` -- `RequiredActionFunctionToolCall object { id, function, type }` +Create a run. - Tool call objects +### Path Parameters - - `id: string` +- `thread_id: string` - The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](/docs/api-reference/runs/submitToolOutputs) endpoint. +### Query Parameters - - `function: object { arguments, name }` +- `include: optional array of RunStepInclude` - The function definition. + A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. - - `arguments: string` + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - The arguments that the model expects you to pass to the function. + - `"step_details.tool_calls[*].file_search.results[*].content"` - - `name: string` +### Body Parameters - The name of the function. +- `assistant_id: string` - - `type: "function"` + The ID of the [assistant](/docs/api-reference/assistants) to use to execute this run. - The type of tool call the output is required for. For now, this is always `function`. +- `additional_instructions: optional string` - - `"function"` + Appends additional instructions at the end of the instructions for the run. This is useful for modifying the behavior on a per-run basis without overriding other instructions. -### Run +- `additional_messages: optional array of object { content, role, attachments, metadata }` -- `Run object { id, assistant_id, cancelled_at, 24 more }` + Adds additional messages to the thread before creating the run. - Represents an execution run on a [thread](/docs/api-reference/threads). + - `content: string or array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlockParam` - - `id: string` + The text contents of the message. - The identifier, which can be referenced in API endpoints. + - `TextContent = string` - - `assistant_id: string` + The text contents of the message. - The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. + - `ArrayOfContentParts = array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlockParam` - - `cancelled_at: number` + An array of content parts with a defined type, each can be of type `text` or images can be passed with `image_url` or `image_file`. Image types are only supported on [Vision-compatible models](/docs/models). - The Unix timestamp (in seconds) for when the run was cancelled. + - `ImageFileContentBlock object { image_file, type }` - - `completed_at: number` + References an image [File](/docs/api-reference/files) in the content of a message. - The Unix timestamp (in seconds) for when the run was completed. + - `image_file: ImageFile` - - `created_at: number` + - `file_id: string` - The Unix timestamp (in seconds) for when the run was created. + The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - `expires_at: number` + - `detail: optional "auto" or "low" or "high"` - The Unix timestamp (in seconds) for when the run will expire. + Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - `failed_at: number` + - `"auto"` - The Unix timestamp (in seconds) for when the run failed. + - `"low"` - - `incomplete_details: object { reason }` + - `"high"` - Details on why the run is incomplete. Will be `null` if the run is not incomplete. + - `type: "image_file"` - - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` + Always `image_file`. - The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + - `"image_file"` - - `"max_completion_tokens"` + - `ImageURLContentBlock object { image_url, type }` - - `"max_prompt_tokens"` + References an image URL in the content of a message. - - `instructions: string` + - `image_url: ImageURL` - The instructions that the [assistant](/docs/api-reference/assistants) used for this run. + - `url: string` - - `last_error: object { code, message }` + The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. - The last error associated with this run. Will be `null` if there are no errors. + - `detail: optional "auto" or "low" or "high"` - - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` + Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` - One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. + - `"auto"` - - `"server_error"` + - `"low"` - - `"rate_limit_exceeded"` + - `"high"` - - `"invalid_prompt"` + - `type: "image_url"` - - `message: string` + The type of the content part. - A human-readable description of the error. + - `"image_url"` - - `max_completion_tokens: number` + - `TextContentBlockParam object { text, type }` - The maximum number of completion tokens specified to have been used over the course of the run. + The text content that is part of a message. - - `max_prompt_tokens: number` + - `text: string` - The maximum number of prompt tokens specified to have been used over the course of the run. + Text content to be sent to the model - - `metadata: Metadata` + - `type: "text"` + + Always `text`. + + - `"text"` + + - `role: "user" or "assistant"` + + The role of the entity that is creating the message. Allowed values include: + + - `user`: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages. + - `assistant`: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation. + + - `"user"` + + - `"assistant"` + + - `attachments: optional array of object { file_id, tools }` + + A list of files attached to the message, and the tools they should be added to. + + - `file_id: optional string` + + The ID of the file to attach to the message. + + - `tools: optional array of CodeInterpreterTool or object { type }` + + The tools to add this file to. + + - `CodeInterpreterTool object { type }` + + - `type: "code_interpreter"` + + The type of tool being defined: `code_interpreter` + + - `"code_interpreter"` + + - `FileSearchTool object { type }` + + - `type: "file_search"` + + The type of tool being defined: `file_search` + + - `"file_search"` + + - `metadata: optional Metadata` Set of 16 key-value pairs that can be attached to an object. This can be useful for storing additional information about the object in a structured @@ -229444,61 +228819,150 @@ curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/cancel \ Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. - - `model: string` +- `instructions: optional string` - The model that the [assistant](/docs/api-reference/assistants) used for this run. + Overrides the [instructions](/docs/api-reference/assistants/createAssistant) of the assistant. This is useful for modifying the behavior on a per-run basis. - - `object: "thread.run"` +- `max_completion_tokens: optional number` - The object type, which is always `thread.run`. + The maximum number of completion tokens that may be used over the course of the run. The run will make a best effort to use only the number of completion tokens specified, across multiple turns of the run. If the run exceeds the number of completion tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info. - - `"thread.run"` +- `max_prompt_tokens: optional number` - - `parallel_tool_calls: boolean` + The maximum number of prompt tokens that may be used over the course of the run. The run will make a best effort to use only the number of prompt tokens specified, across multiple turns of the run. If the run exceeds the number of prompt tokens specified, the run will end with status `incomplete`. See `incomplete_details` for more info. - Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. +- `metadata: optional Metadata` - - `required_action: object { submit_tool_outputs, 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. - Details on the action required to continue the run. Will be `null` if no action is required. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `submit_tool_outputs: object { tool_calls }` +- `model: optional string or "gpt-5" or "gpt-5-mini" or "gpt-5-nano" or 39 more` - Details on the tool outputs needed for this run to continue. + The ID of the [Model](/docs/api-reference/models) to be used to execute this run. If a value is provided here, it will override the model associated with the assistant. If not, the model associated with the assistant will be used. - - `tool_calls: array of RequiredActionFunctionToolCall` + - `string` - A list of the relevant tool calls. + - `AssistantSupportedModels = "gpt-5" or "gpt-5-mini" or "gpt-5-nano" or 39 more` - - `id: string` + The ID of the [Model](/docs/api-reference/models) to be used to execute this run. If a value is provided here, it will override the model associated with the assistant. If not, the model associated with the assistant will be used. - The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](/docs/api-reference/runs/submitToolOutputs) endpoint. + - `"gpt-5"` - - `function: object { arguments, name }` + - `"gpt-5-mini"` - The function definition. + - `"gpt-5-nano"` - - `arguments: string` + - `"gpt-5-2025-08-07"` - The arguments that the model expects you to pass to the function. + - `"gpt-5-mini-2025-08-07"` - - `name: string` + - `"gpt-5-nano-2025-08-07"` - The name of the function. + - `"gpt-4.1"` - - `type: "function"` + - `"gpt-4.1-mini"` - The type of tool call the output is required for. For now, this is always `function`. + - `"gpt-4.1-nano"` - - `"function"` + - `"gpt-4.1-2025-04-14"` - - `type: "submit_tool_outputs"` + - `"gpt-4.1-mini-2025-04-14"` - For now, this is always `submit_tool_outputs`. + - `"gpt-4.1-nano-2025-04-14"` - - `"submit_tool_outputs"` + - `"o3-mini"` - - `response_format: AssistantResponseFormatOption` + - `"o3-mini-2025-01-31"` + + - `"o1"` + + - `"o1-2024-12-17"` + + - `"gpt-4o"` + + - `"gpt-4o-2024-11-20"` + + - `"gpt-4o-2024-08-06"` + + - `"gpt-4o-2024-05-13"` + + - `"gpt-4o-mini"` + + - `"gpt-4o-mini-2024-07-18"` + + - `"gpt-4.5-preview"` + + - `"gpt-4.5-preview-2025-02-27"` + + - `"gpt-4-turbo"` + + - `"gpt-4-turbo-2024-04-09"` + + - `"gpt-4-0125-preview"` + + - `"gpt-4-turbo-preview"` + + - `"gpt-4-1106-preview"` + + - `"gpt-4-vision-preview"` + + - `"gpt-4"` + + - `"gpt-4-0314"` + + - `"gpt-4-0613"` + + - `"gpt-4-32k"` + + - `"gpt-4-32k-0314"` + + - `"gpt-4-32k-0613"` + + - `"gpt-3.5-turbo"` + + - `"gpt-3.5-turbo-16k"` + + - `"gpt-3.5-turbo-0613"` + + - `"gpt-3.5-turbo-1106"` + + - `"gpt-3.5-turbo-0125"` + + - `"gpt-3.5-turbo-16k-0613"` + +- `parallel_tool_calls: optional boolean` + + Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. + +- `reasoning_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"` + +- `response_format: optional AssistantResponseFormatOption` Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. @@ -229575,37 +229039,15 @@ curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/cancel \ - `"json_schema"` - - `started_at: number` - - The Unix timestamp (in seconds) for when the run was started. - - - `status: "queued" or "in_progress" or "requires_action" or 6 more` - - The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - - `"queued"` - - - `"in_progress"` - - - `"requires_action"` - - - `"cancelling"` - - - `"cancelled"` - - - `"failed"` - - - `"completed"` - - - `"incomplete"` +- `stream: optional boolean` - - `"expired"` + If `true`, returns a stream of events that happen during the Run as server-sent events, terminating when the Run enters a terminal state with a `data: [DONE]` message. - - `thread_id: string` +- `temperature: optional number` - The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. + 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. - - `tool_choice: AssistantToolChoiceOption` +- `tool_choice: optional AssistantToolChoiceOption` Controls which (if any) tool is called by the model. `none` means the model will not call any tools and instead generates a message. @@ -229643,18 +229085,12 @@ curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/cancel \ The name of the function to call. - - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` +- `tools: optional array of CodeInterpreterTool or FileSearchTool or FunctionTool` - The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. + Override the tools the assistant can use for this run. This is useful for modifying the behavior on a per-run basis. - `CodeInterpreterTool object { type }` - - `type: "code_interpreter"` - - The type of tool being defined: `code_interpreter` - - - `"code_interpreter"` - - `FileSearchTool object { type, file_search }` - `type: "file_search"` @@ -229719,7 +229155,13 @@ curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/cancel \ - `"function"` - - `truncation_strategy: object { type, last_messages }` +- `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 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. + +- `truncation_strategy: optional object { type, last_messages }` Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. @@ -229735,544 +229177,789 @@ curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/cancel \ The number of most recent messages from the thread when constructing the context for the run. - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - - - `completion_tokens: number` +### Returns - Number of completion tokens used over the course of the run. +- `Run object { id, assistant_id, cancelled_at, 24 more }` - - `prompt_tokens: number` + Represents an execution run on a [thread](/docs/api-reference/threads). - Number of prompt tokens used over the course of the run. + - `id: string` - - `total_tokens: number` + The identifier, which can be referenced in API endpoints. - Total number of tokens used (prompt + completion). + - `assistant_id: string` - - `temperature: optional number` + The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. - The sampling temperature used for this run. If not set, defaults to 1. + - `cancelled_at: number` - - `top_p: optional number` + The Unix timestamp (in seconds) for when the run was cancelled. - The nucleus sampling value used for this run. If not set, defaults to 1. + - `completed_at: number` -# Steps + The Unix timestamp (in seconds) for when the run was completed. -## List run steps + - `created_at: number` -**get** `/threads/{thread_id}/runs/{run_id}/steps` + The Unix timestamp (in seconds) for when the run was created. -Returns a list of run steps belonging to a run. + - `expires_at: number` -### Path Parameters + The Unix timestamp (in seconds) for when the run will expire. -- `thread_id: string` + - `failed_at: number` -- `run_id: string` + The Unix timestamp (in seconds) for when the run failed. -### Query Parameters + - `incomplete_details: object { reason }` -- `after: optional string` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. + - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` -- `before: optional string` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. + - `"max_completion_tokens"` -- `include: optional array of RunStepInclude` + - `"max_prompt_tokens"` - A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. + - `instructions: string` - See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + The instructions that the [assistant](/docs/api-reference/assistants) used for this run. - - `"step_details.tool_calls[*].file_search.results[*].content"` + - `last_error: object { code, message }` -- `limit: optional number` + The last error associated with this run. Will be `null` if there are no errors. - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` -- `order: optional "asc" or "desc"` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. + - `"server_error"` - - `"asc"` + - `"rate_limit_exceeded"` - - `"desc"` + - `"invalid_prompt"` -### Returns + - `message: string` -- `data: array of RunStep` + A human-readable description of the error. - - `id: string` + - `max_completion_tokens: number` - The identifier of the run step, which can be referenced in API endpoints. + The maximum number of completion tokens specified to have been used over the course of the run. - - `assistant_id: string` + - `max_prompt_tokens: number` - The ID of the [assistant](/docs/api-reference/assistants) associated with the run step. + The maximum number of prompt tokens specified to have been used over the course of the run. - - `cancelled_at: number` + - `metadata: Metadata` - The Unix timestamp (in seconds) for when the run step was cancelled. + 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. - - `completed_at: number` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - The Unix timestamp (in seconds) for when the run step completed. + - `model: string` - - `created_at: number` + The model that the [assistant](/docs/api-reference/assistants) used for this run. - The Unix timestamp (in seconds) for when the run step was created. + - `object: "thread.run"` - - `expired_at: number` + The object type, which is always `thread.run`. - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + - `"thread.run"` - - `failed_at: number` + - `parallel_tool_calls: boolean` - The Unix timestamp (in seconds) for when the run step failed. + Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `last_error: object { code, message }` + - `required_action: object { submit_tool_outputs, type }` - The last error associated with this run step. Will be `null` if there are no errors. + Details on the action required to continue the run. Will be `null` if no action is required. - - `code: "server_error" or "rate_limit_exceeded"` + - `submit_tool_outputs: object { tool_calls }` - One of `server_error` or `rate_limit_exceeded`. + Details on the tool outputs needed for this run to continue. - - `"server_error"` + - `tool_calls: array of RequiredActionFunctionToolCall` - - `"rate_limit_exceeded"` + A list of the relevant tool calls. - - `message: string` + - `id: string` - A human-readable description of the error. + The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](/docs/api-reference/runs/submitToolOutputs) endpoint. - - `metadata: Metadata` + - `function: object { arguments, name }` - 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 function definition. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `arguments: string` - - `object: "thread.run.step"` + The arguments that the model expects you to pass to the function. - The object type, which is always `thread.run.step`. + - `name: string` - - `"thread.run.step"` + The name of the function. - - `run_id: string` + - `type: "function"` - The ID of the [run](/docs/api-reference/runs) that this run step is a part of. + The type of tool call the output is required for. For now, this is always `function`. - - `status: "in_progress" or "cancelled" or "failed" or 2 more` + - `"function"` - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + - `type: "submit_tool_outputs"` - - `"in_progress"` + For now, this is always `submit_tool_outputs`. - - `"cancelled"` + - `"submit_tool_outputs"` - - `"failed"` + - `response_format: AssistantResponseFormatOption` - - `"completed"` + Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `"expired"` + Setting to `{ "type": "json_schema", "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). - - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - The details of the run step. + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `MessageCreationStepDetails object { message_creation, type }` + - `"auto"` - Details of the message creation by the run step. + `auto` is the default value - - `message_creation: object { message_id }` + - `"auto"` - - `message_id: string` + - `ResponseFormatText object { type }` - The ID of the message that was created by this run step. + Default response format. Used to generate text responses. - - `type: "message_creation"` + - `type: "text"` - Always `message_creation`. + The type of response format being defined. Always `text`. - - `"message_creation"` + - `"text"` - - `ToolCallsStepDetails object { tool_calls, type }` + - `ResponseFormatJSONObject object { type }` - Details of the tool call. + 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. - - `tool_calls: array of CodeInterpreterToolCall or FileSearchToolCall or FunctionToolCall` + - `type: "json_object"` - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + The type of response format being defined. Always `json_object`. - - `CodeInterpreterToolCall object { id, code_interpreter, type }` + - `"json_object"` - Details of the Code Interpreter tool call the run step was involved in. + - `ResponseFormatJSONSchema object { json_schema, type }` - - `id: string` + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - The ID of the tool call. + - `json_schema: object { name, description, schema, strict }` - - `code_interpreter: object { input, outputs }` + Structured Outputs configuration options, including a JSON Schema. - The Code Interpreter tool call definition. + - `name: string` - - `input: 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 input to the Code Interpreter tool call. + - `description: optional string` - - `outputs: array of object { logs, type } or object { image, type }` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. + - `schema: optional map[unknown]` - - `CodeInterpreterLogOutput object { logs, type }` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - Text output from the Code Interpreter tool call as part of a run step. + - `strict: optional boolean` - - `logs: 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 text output from the Code Interpreter tool call. + - `type: "json_schema"` - - `type: "logs"` + The type of response format being defined. Always `json_schema`. - Always `logs`. + - `"json_schema"` - - `"logs"` + - `started_at: number` - - `CodeInterpreterImageOutput object { image, type }` + The Unix timestamp (in seconds) for when the run was started. - - `image: object { file_id }` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - - `file_id: string` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - The [file](/docs/api-reference/files) ID of the image. + - `"queued"` - - `type: "image"` + - `"in_progress"` - Always `image`. + - `"requires_action"` - - `"image"` + - `"cancelling"` - - `type: "code_interpreter"` + - `"cancelled"` - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + - `"failed"` - - `"code_interpreter"` + - `"completed"` - - `FileSearchToolCall object { id, file_search, type }` + - `"incomplete"` - - `id: string` + - `"expired"` - The ID of the tool call object. + - `thread_id: string` - - `file_search: object { ranking_options, results }` + The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. - For now, this is always going to be an empty object. + - `tool_choice: AssistantToolChoiceOption` - - `ranking_options: optional object { ranker, score_threshold }` + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - The ranking options for the file search. + - `"none" or "auto" or "required"` - - `ranker: "auto" or "default_2024_08_21"` + `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `"none"` - `"auto"` - - `"default_2024_08_21"` + - `"required"` - - `score_threshold: number` + - `AssistantToolChoice object { type, function }` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `results: optional array of object { file_id, file_name, score, content }` + - `type: "function" or "code_interpreter" or "file_search"` - The results of the file search. + The type of the tool. If type is `function`, the function name must be set - - `file_id: string` + - `"function"` - The ID of the file that result was found in. + - `"code_interpreter"` - - `file_name: string` + - `"file_search"` - The name of the file that result was found in. + - `function: optional AssistantToolChoiceFunction` - - `score: number` + - `name: string` - The score of the result. All values must be a floating point number between 0 and 1. + The name of the function to call. - - `content: optional array of object { text, type }` + - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` - The content of the result that was found. The content is only included if requested via the include query parameter. + The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. - - `text: optional string` + - `CodeInterpreterTool object { type }` - The text content of the file. + - `type: "code_interpreter"` - - `type: optional "text"` + The type of tool being defined: `code_interpreter` - The type of the content. + - `"code_interpreter"` - - `"text"` + - `FileSearchTool object { type, file_search }` - `type: "file_search"` - The type of tool call. This is always going to be `file_search` for this type of tool call. + The type of tool being defined: `file_search` - `"file_search"` - - `FunctionToolCall object { id, function, type }` + - `file_search: optional object { max_num_results, ranking_options }` - - `id: string` + Overrides for the file search tool. - The ID of the tool call object. + - `max_num_results: optional number` - - `function: object { arguments, name, output }` + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - The definition of the function that was called. + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `arguments: string` + - `ranking_options: optional object { score_threshold, ranker }` - The arguments passed to the function. + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `score_threshold: number` + + The score threshold for the file search. All values must be a floating point number between 0 and 1. + + - `ranker: optional "auto" or "default_2024_08_21"` + + The ranker to use for the file search. If not specified will use the `auto` ranker. + + - `"auto"` + + - `"default_2024_08_21"` + + - `FunctionTool object { function, type }` + + - `function: FunctionDefinition` - `name: string` - The name of the function. + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `output: string` + - `description: optional string` - The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. + A description of what the function does, used by the model to choose when and how to call the function. + + - `parameters: optional FunctionParameters` + + The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + + Omitting `parameters` defines a function with an empty parameter list. + + - `strict: optional boolean` + + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-calling). - `type: "function"` - The type of tool call. This is always going to be `function` for this type of tool call. + The type of tool being defined: `function` - `"function"` - - `type: "tool_calls"` - - Always `tool_calls`. + - `truncation_strategy: object { type, last_messages }` - - `"tool_calls"` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `thread_id: string` + - `type: "auto" or "last_messages"` - The ID of the [thread](/docs/api-reference/threads) that was run. + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. - - `type: "message_creation" or "tool_calls"` + - `"auto"` - The type of run step, which can be either `message_creation` or `tool_calls`. + - `"last_messages"` - - `"message_creation"` + - `last_messages: optional number` - - `"tool_calls"` + The number of most recent messages from the thread when constructing the context for the run. - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - `completion_tokens: number` - Number of completion tokens used over the course of the run step. + Number of completion tokens used over the course of the run. - `prompt_tokens: number` - Number of prompt tokens used over the course of the run step. + Number of prompt tokens used over the course of the run. - `total_tokens: number` Total number of tokens used (prompt + completion). -- `first_id: string` + - `temperature: optional number` -- `has_more: boolean` + The sampling temperature used for this run. If not set, defaults to 1. -- `last_id: string` + - `top_p: optional number` -- `object: string` + The nucleus sampling value used for this run. If not set, defaults to 1. ### Example ```http -curl https://api.openai.com/v1/threads/$THREAD_ID/runs/$RUN_ID/steps \ +curl https://api.openai.com/v1/threads/$THREAD_ID/runs \ + -H 'Content-Type: application/json' \ -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "assistant_id": "assistant_id", + "temperature": 1, + "top_p": 1 + }' ``` #### Response ```json { - "data": [ - { "id": "id", "assistant_id": "assistant_id", "cancelled_at": 0, "completed_at": 0, "created_at": 0, - "expired_at": 0, + "expires_at": 0, "failed_at": 0, + "incomplete_details": { + "reason": "max_completion_tokens" + }, + "instructions": "instructions", "last_error": { "code": "server_error", "message": "message" }, + "max_completion_tokens": 256, + "max_prompt_tokens": 256, "metadata": { "foo": "string" }, - "object": "thread.run.step", - "run_id": "run_id", - "status": "in_progress", - "step_details": { - "message_creation": { - "message_id": "message_id" + "model": "model", + "object": "thread.run", + "parallel_tool_calls": true, + "required_action": { + "submit_tool_outputs": { + "tool_calls": [ + { + "id": "id", + "function": { + "arguments": "arguments", + "name": "name" }, - "type": "message_creation" + "type": "function" + } + ] }, + "type": "submit_tool_outputs" + }, + "response_format": "auto", + "started_at": 0, + "status": "queued", "thread_id": "thread_id", - "type": "message_creation", + "tool_choice": "none", + "tools": [ + { + "type": "code_interpreter" + } + ], + "truncation_strategy": { + "type": "auto", + "last_messages": 1 + }, "usage": { "completion_tokens": 0, "prompt_tokens": 0, "total_tokens": 0 - } - } - ], - "first_id": "step_abc123", - "has_more": false, - "last_id": "step_abc456", - "object": "list" + }, + "temperature": 0, + "top_p": 0 } ``` ### Example ```http -curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/steps \ +curl https://api.openai.com/v1/threads/thread_abc123/runs \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ - -H "OpenAI-Beta: assistants=v2" + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "assistant_id": "asst_abc123" + }' ``` #### Response ```json { - "object": "list", - "data": [ - { - "id": "step_abc123", - "object": "thread.run.step", - "created_at": 1699063291, - "run_id": "run_abc123", + "id": "run_abc123", + "object": "thread.run", + "created_at": 1699063290, "assistant_id": "asst_abc123", "thread_id": "thread_abc123", - "type": "message_creation", - "status": "completed", + "status": "queued", + "started_at": 1699063290, + "expires_at": null, "cancelled_at": null, - "completed_at": 1699063291, - "expired_at": null, "failed_at": null, + "completed_at": 1699063291, "last_error": null, - "step_details": { - "type": "message_creation", - "message_creation": { - "message_id": "msg_abc123" + "model": "gpt-4o", + "instructions": null, + "incomplete_details": null, + "tools": [ + { + "type": "code_interpreter" + } + ], + "metadata": {}, + "usage": null, + "temperature": 1.0, + "top_p": 1.0, + "max_prompt_tokens": 1000, + "max_completion_tokens": 1000, + "truncation_strategy": { + "type": "auto", + "last_messages": null + }, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true +} +``` + +### Streaming + +```http +curl https://api.openai.com/v1/threads/thread_123/runs \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "assistant_id": "asst_123", + "stream": true + }' +``` + +#### Response + +```json +event: thread.run.created +data: {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710331240,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + +event: thread.run.queued +data: {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710331240,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + +event: thread.run.in_progress +data: {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710330641,"expires_at":1710331240,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + +event: thread.run.step.created +data: {"id":"step_001","object":"thread.run.step","created_at":1710330641,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710331240,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} + +event: thread.run.step.in_progress +data: {"id":"step_001","object":"thread.run.step","created_at":1710330641,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710331240,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} + +event: thread.message.created +data: {"id":"msg_001","object":"thread.message","created_at":1710330641,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} + +event: thread.message.in_progress +data: {"id":"msg_001","object":"thread.message","created_at":1710330641,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} + +event: thread.message.delta +data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"Hello","annotations":[]}}]}} + +... + +event: thread.message.delta +data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" today"}}]}} + +event: thread.message.delta +data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"?"}}]}} + +event: thread.message.completed +data: {"id":"msg_001","object":"thread.message","created_at":1710330641,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"completed","incomplete_details":null,"incomplete_at":null,"completed_at":1710330642,"role":"assistant","content":[{"type":"text","text":{"value":"Hello! How can I assist you today?","annotations":[]}}],"metadata":{}} + +event: thread.run.step.completed +data: {"id":"step_001","object":"thread.run.step","created_at":1710330641,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"completed","cancelled_at":null,"completed_at":1710330642,"expires_at":1710331240,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31}} + +event: thread.run.completed +data: {"id":"run_123","object":"thread.run","created_at":1710330640,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1710330641,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1710330642,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + +event: done +data: [DONE] +``` + +### Streaming with Functions + +```http +curl https://api.openai.com/v1/threads/thread_abc123/runs \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "assistant_id": "asst_abc123", + "tools": [ + { + "type": "function", + "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"] } }, - "usage": { - "prompt_tokens": 123, - "completion_tokens": 456, - "total_tokens": 579 + "required": ["location"] + } } } ], - "first_id": "step_abc123", - "last_id": "step_abc456", - "has_more": false -} + "stream": true + }' +``` + +#### Response + +```json +event: thread.run.created +data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + +event: thread.run.queued +data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":null,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + +event: thread.run.in_progress +data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710348075,"expires_at":1710348675,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + +event: thread.run.step.created +data: {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} + +event: thread.run.step.in_progress +data: {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":null} + +event: thread.message.created +data: {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} + +event: thread.message.in_progress +data: {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} + +event: thread.message.delta +data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"Hello","annotations":[]}}]}} + +... + +event: thread.message.delta +data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" today"}}]}} + +event: thread.message.delta +data: {"id":"msg_001","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"?"}}]}} + +event: thread.message.completed +data: {"id":"msg_001","object":"thread.message","created_at":1710348076,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"completed","incomplete_details":null,"incomplete_at":null,"completed_at":1710348077,"role":"assistant","content":[{"type":"text","text":{"value":"Hello! How can I assist you today?","annotations":[]}}],"metadata":{}} + +event: thread.run.step.completed +data: {"id":"step_001","object":"thread.run.step","created_at":1710348076,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"completed","cancelled_at":null,"completed_at":1710348077,"expires_at":1710348675,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_001"}},"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31}} + +event: thread.run.completed +data: {"id":"run_123","object":"thread.run","created_at":1710348075,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1710348075,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1710348077,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} + +event: done +data: [DONE] ``` -## Retrieve run step +## List runs -**get** `/threads/{thread_id}/runs/{run_id}/steps/{step_id}` +**get** `/threads/{thread_id}/runs` -Retrieves a run step. +Returns a list of runs belonging to a thread. ### Path Parameters - `thread_id: string` -- `run_id: string` +### Query Parameters -- `step_id: string` +- `after: optional string` -### Query Parameters + A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. -- `include: optional array of RunStepInclude` +- `before: optional string` - A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. + A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. - See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. +- `limit: optional number` - - `"step_details.tool_calls[*].file_search.results[*].content"` + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. -### Returns +- `order: optional "asc" or "desc"` -- `RunStep object { id, assistant_id, cancelled_at, 13 more }` + Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. - Represents a step in execution of a run. + - `"asc"` + + - `"desc"` + +### Returns + +- `data: array of Run` - `id: string` - The identifier of the run step, which can be referenced in API endpoints. + The identifier, which can be referenced in API endpoints. - `assistant_id: string` - The ID of the [assistant](/docs/api-reference/assistants) associated with the run step. + The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. - `cancelled_at: number` - The Unix timestamp (in seconds) for when the run step was cancelled. + The Unix timestamp (in seconds) for when the run was cancelled. - `completed_at: number` - The Unix timestamp (in seconds) for when the run step completed. + The Unix timestamp (in seconds) for when the run was completed. - `created_at: number` - The Unix timestamp (in seconds) for when the run step was created. + The Unix timestamp (in seconds) for when the run was created. - - `expired_at: number` + - `expires_at: number` - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + The Unix timestamp (in seconds) for when the run will expire. - `failed_at: number` - The Unix timestamp (in seconds) for when the run step failed. + The Unix timestamp (in seconds) for when the run failed. + + - `incomplete_details: object { reason }` + + Details on why the run is incomplete. Will be `null` if the run is not incomplete. + + - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` + + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. + + - `"max_completion_tokens"` + + - `"max_prompt_tokens"` + + - `instructions: string` + + The instructions that the [assistant](/docs/api-reference/assistants) used for this run. - `last_error: object { code, message }` - The last error associated with this run step. Will be `null` if there are no errors. + The last error associated with this run. Will be `null` if there are no errors. - - `code: "server_error" or "rate_limit_exceeded"` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` - One of `server_error` or `rate_limit_exceeded`. + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - `"server_error"` - `"rate_limit_exceeded"` + - `"invalid_prompt"` + - `message: string` A human-readable description of the error. + - `max_completion_tokens: number` + + The maximum number of completion tokens specified to have been used over the course of the run. + + - `max_prompt_tokens: number` + + The maximum number of prompt tokens specified to have been used over the course of the run. + - `metadata: Metadata` Set of 16 key-value pairs that can be attached to an object. This can be @@ -230282,240 +229969,333 @@ Retrieves a run step. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. - - `object: "thread.run.step"` + - `model: string` - The object type, which is always `thread.run.step`. + The model that the [assistant](/docs/api-reference/assistants) used for this run. - - `"thread.run.step"` + - `object: "thread.run"` - - `run_id: string` + The object type, which is always `thread.run`. - The ID of the [run](/docs/api-reference/runs) that this run step is a part of. + - `"thread.run"` - - `status: "in_progress" or "cancelled" or "failed" or 2 more` + - `parallel_tool_calls: boolean` - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `"in_progress"` + - `required_action: object { submit_tool_outputs, type }` - - `"cancelled"` + Details on the action required to continue the run. Will be `null` if no action is required. - - `"failed"` + - `submit_tool_outputs: object { tool_calls }` - - `"completed"` + Details on the tool outputs needed for this run to continue. - - `"expired"` + - `tool_calls: array of RequiredActionFunctionToolCall` - - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` + A list of the relevant tool calls. - The details of the run step. + - `id: string` - - `MessageCreationStepDetails object { message_creation, type }` + The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](/docs/api-reference/runs/submitToolOutputs) endpoint. - Details of the message creation by the run step. + - `function: object { arguments, name }` - - `message_creation: object { message_id }` + The function definition. - - `message_id: string` + - `arguments: string` - The ID of the message that was created by this run step. + The arguments that the model expects you to pass to the function. - - `type: "message_creation"` + - `name: string` - Always `message_creation`. + The name of the function. - - `"message_creation"` + - `type: "function"` - - `ToolCallsStepDetails object { tool_calls, type }` + The type of tool call the output is required for. For now, this is always `function`. - Details of the tool call. + - `"function"` - - `tool_calls: array of CodeInterpreterToolCall or FileSearchToolCall or FunctionToolCall` + - `type: "submit_tool_outputs"` - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + For now, this is always `submit_tool_outputs`. - - `CodeInterpreterToolCall object { id, code_interpreter, type }` + - `"submit_tool_outputs"` - Details of the Code Interpreter tool call the run step was involved in. + - `response_format: AssistantResponseFormatOption` - - `id: string` + Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - The ID of the tool call. + Setting to `{ "type": "json_schema", "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). - - `code_interpreter: object { input, outputs }` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - The Code Interpreter tool call definition. + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - - `input: string` + - `"auto"` - The input to the Code Interpreter tool call. + `auto` is the default value - - `outputs: array of object { logs, type } or object { image, type }` + - `"auto"` - The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. + - `ResponseFormatText object { type }` - - `CodeInterpreterLogOutput object { logs, type }` + Default response format. Used to generate text responses. - Text output from the Code Interpreter tool call as part of a run step. + - `type: "text"` - - `logs: string` + The type of response format being defined. Always `text`. - The text output from the Code Interpreter tool call. + - `"text"` - - `type: "logs"` + - `ResponseFormatJSONObject object { type }` - Always `logs`. + 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. - - `"logs"` + - `type: "json_object"` - - `CodeInterpreterImageOutput object { image, type }` + The type of response format being defined. Always `json_object`. - - `image: object { file_id }` + - `"json_object"` - - `file_id: string` + - `ResponseFormatJSONSchema object { json_schema, type }` - The [file](/docs/api-reference/files) ID of the image. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `type: "image"` + - `json_schema: object { name, description, schema, strict }` - Always `image`. + Structured Outputs configuration options, including a JSON Schema. - - `"image"` + - `name: string` - - `type: "code_interpreter"` + 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 type of tool call. This is always going to be `code_interpreter` for this type of tool call. + - `description: optional string` - - `"code_interpreter"` + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `FileSearchToolCall object { id, file_search, type }` + - `schema: optional map[unknown]` - - `id: string` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - The ID of the tool call object. + - `strict: optional boolean` - - `file_search: object { ranking_options, results }` + 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). - For now, this is always going to be an empty object. + - `type: "json_schema"` - - `ranking_options: optional object { ranker, score_threshold }` + The type of response format being defined. Always `json_schema`. - The ranking options for the file search. + - `"json_schema"` - - `ranker: "auto" or "default_2024_08_21"` + - `started_at: number` - The ranker to use for the file search. If not specified will use the `auto` ranker. + The Unix timestamp (in seconds) for when the run was started. + + - `status: "queued" or "in_progress" or "requires_action" or 6 more` + + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + + - `"queued"` + + - `"in_progress"` + + - `"requires_action"` + + - `"cancelling"` + + - `"cancelled"` + + - `"failed"` + + - `"completed"` + + - `"incomplete"` + + - `"expired"` + + - `thread_id: string` + + The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. + + - `tool_choice: AssistantToolChoiceOption` + + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + + - `"none" or "auto" or "required"` + + `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. + + - `"none"` - `"auto"` - - `"default_2024_08_21"` + - `"required"` - - `score_threshold: number` + - `AssistantToolChoice object { type, function }` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `results: optional array of object { file_id, file_name, score, content }` + - `type: "function" or "code_interpreter" or "file_search"` - The results of the file search. + The type of the tool. If type is `function`, the function name must be set - - `file_id: string` + - `"function"` - The ID of the file that result was found in. + - `"code_interpreter"` - - `file_name: string` + - `"file_search"` - The name of the file that result was found in. + - `function: optional AssistantToolChoiceFunction` - - `score: number` + - `name: string` - The score of the result. All values must be a floating point number between 0 and 1. + The name of the function to call. - - `content: optional array of object { text, type }` + - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` - The content of the result that was found. The content is only included if requested via the include query parameter. + The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. - - `text: optional string` + - `CodeInterpreterTool object { type }` - The text content of the file. + - `type: "code_interpreter"` - - `type: optional "text"` + The type of tool being defined: `code_interpreter` - The type of the content. + - `"code_interpreter"` - - `"text"` + - `FileSearchTool object { type, file_search }` - `type: "file_search"` - The type of tool call. This is always going to be `file_search` for this type of tool call. + The type of tool being defined: `file_search` - `"file_search"` - - `FunctionToolCall object { id, function, type }` + - `file_search: optional object { max_num_results, ranking_options }` - - `id: string` + Overrides for the file search tool. - The ID of the tool call object. + - `max_num_results: optional number` - - `function: object { arguments, name, output }` + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - The definition of the function that was called. + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `arguments: string` + - `ranking_options: optional object { score_threshold, ranker }` - The arguments passed to the function. + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. + + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `score_threshold: number` + + The score threshold for the file search. All values must be a floating point number between 0 and 1. + + - `ranker: optional "auto" or "default_2024_08_21"` + + The ranker to use for the file search. If not specified will use the `auto` ranker. + + - `"auto"` + + - `"default_2024_08_21"` + + - `FunctionTool object { function, type }` + + - `function: FunctionDefinition` - `name: string` - The name of the function. + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `output: string` + - `description: optional string` - The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. + A description of what the function does, used by the model to choose when and how to call the function. + + - `parameters: optional FunctionParameters` + + The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. + + Omitting `parameters` defines a function with an empty parameter list. + + - `strict: optional boolean` + + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-calling). - `type: "function"` - The type of tool call. This is always going to be `function` for this type of tool call. + The type of tool being defined: `function` - `"function"` - - `type: "tool_calls"` - - Always `tool_calls`. + - `truncation_strategy: object { type, last_messages }` - - `"tool_calls"` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `thread_id: string` + - `type: "auto" or "last_messages"` - The ID of the [thread](/docs/api-reference/threads) that was run. + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. - - `type: "message_creation" or "tool_calls"` + - `"auto"` - The type of run step, which can be either `message_creation` or `tool_calls`. + - `"last_messages"` - - `"message_creation"` + - `last_messages: optional number` - - `"tool_calls"` + The number of most recent messages from the thread when constructing the context for the run. - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - `completion_tokens: number` - Number of completion tokens used over the course of the run step. + Number of completion tokens used over the course of the run. - `prompt_tokens: number` - Number of prompt tokens used over the course of the run step. + Number of prompt tokens used over the course of the run. - `total_tokens: number` Total number of tokens used (prompt + completion). + - `temperature: optional number` + + The sampling temperature used for this run. If not set, defaults to 1. + + - `top_p: optional number` + + The nucleus sampling value used for this run. If not set, defaults to 1. + +- `first_id: string` + +- `has_more: boolean` + +- `last_id: string` + +- `object: string` + ### Example ```http -curl https://api.openai.com/v1/threads/$THREAD_ID/runs/$RUN_ID/steps/$STEP_ID \ +curl https://api.openai.com/v1/threads/$THREAD_ID/runs \ -H 'OpenAI-Beta: assistants=v2' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` @@ -230524,43 +230304,80 @@ curl https://api.openai.com/v1/threads/$THREAD_ID/runs/$RUN_ID/steps/$STEP_ID \ ```json { + "data": [ + { "id": "id", "assistant_id": "assistant_id", "cancelled_at": 0, "completed_at": 0, "created_at": 0, - "expired_at": 0, + "expires_at": 0, "failed_at": 0, + "incomplete_details": { + "reason": "max_completion_tokens" + }, + "instructions": "instructions", "last_error": { "code": "server_error", "message": "message" }, + "max_completion_tokens": 256, + "max_prompt_tokens": 256, "metadata": { "foo": "string" }, - "object": "thread.run.step", - "run_id": "run_id", - "status": "in_progress", - "step_details": { - "message_creation": { - "message_id": "message_id" + "model": "model", + "object": "thread.run", + "parallel_tool_calls": true, + "required_action": { + "submit_tool_outputs": { + "tool_calls": [ + { + "id": "id", + "function": { + "arguments": "arguments", + "name": "name" }, - "type": "message_creation" + "type": "function" + } + ] + }, + "type": "submit_tool_outputs" }, + "response_format": "auto", + "started_at": 0, + "status": "queued", "thread_id": "thread_id", - "type": "message_creation", + "tool_choice": "none", + "tools": [ + { + "type": "code_interpreter" + } + ], + "truncation_strategy": { + "type": "auto", + "last_messages": 1 + }, "usage": { "completion_tokens": 0, "prompt_tokens": 0, "total_tokens": 0 + }, + "temperature": 0, + "top_p": 0 } + ], + "first_id": "run_abc123", + "has_more": false, + "last_id": "run_abc456", + "object": "list" } ``` ### Example ```http -curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/steps/step_abc123 \ +curl https://api.openai.com/v1/threads/thread_abc123/runs \ -H "Authorization: Bearer $OPENAI_API_KEY" \ -H "Content-Type: application/json" \ -H "OpenAI-Beta: assistants=v2" @@ -230570,2050 +230387,2393 @@ curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/steps/step_ ```json { - "id": "step_abc123", - "object": "thread.run.step", - "created_at": 1699063291, - "run_id": "run_abc123", + "object": "list", + "data": [ + { + "id": "run_abc123", + "object": "thread.run", + "created_at": 1699075072, "assistant_id": "asst_abc123", "thread_id": "thread_abc123", - "type": "message_creation", "status": "completed", + "started_at": 1699075072, + "expires_at": null, "cancelled_at": null, - "completed_at": 1699063291, - "expired_at": null, "failed_at": null, + "completed_at": 1699075073, "last_error": null, - "step_details": { - "type": "message_creation", - "message_creation": { - "message_id": "msg_abc123" + "model": "gpt-4o", + "instructions": null, + "incomplete_details": null, + "tools": [ + { + "type": "code_interpreter" + } + ], + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "file-abc123", + "file-abc456" + ] + } + }, + "metadata": {}, + "usage": { + "prompt_tokens": 123, + "completion_tokens": 456, + "total_tokens": 579 + }, + "temperature": 1.0, + "top_p": 1.0, + "max_prompt_tokens": 1000, + "max_completion_tokens": 1000, + "truncation_strategy": { + "type": "auto", + "last_messages": null + }, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true + }, + { + "id": "run_abc456", + "object": "thread.run", + "created_at": 1699063290, + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "status": "completed", + "started_at": 1699063290, + "expires_at": null, + "cancelled_at": null, + "failed_at": null, + "completed_at": 1699063291, + "last_error": null, + "model": "gpt-4o", + "instructions": null, + "incomplete_details": null, + "tools": [ + { + "type": "code_interpreter" + } + ], + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "file-abc123", + "file-abc456" + ] } }, + "metadata": {}, "usage": { "prompt_tokens": 123, "completion_tokens": 456, "total_tokens": 579 + }, + "temperature": 1.0, + "top_p": 1.0, + "max_prompt_tokens": 1000, + "max_completion_tokens": 1000, + "truncation_strategy": { + "type": "auto", + "last_messages": null + }, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true } + ], + "first_id": "run_abc123", + "last_id": "run_abc456", + "has_more": false } ``` -## Domain Types - -### Code Interpreter Logs - -- `CodeInterpreterLogs object { index, type, logs }` - - Text output from the Code Interpreter tool call as part of a run step. - - - `index: number` - - The index of the output in the outputs array. - - - `type: "logs"` - - Always `logs`. - - - `"logs"` - - - `logs: optional string` - - The text output from the Code Interpreter tool call. - -### Code Interpreter Output Image - -- `CodeInterpreterOutputImage object { index, type, image }` - - - `index: number` - - The index of the output in the outputs array. - - - `type: "image"` +## Retrieve run - Always `image`. +**get** `/threads/{thread_id}/runs/{run_id}` - - `"image"` +Retrieves a run. - - `image: optional object { file_id }` +### Path Parameters - - `file_id: optional string` +- `thread_id: string` - The [file](/docs/api-reference/files) ID of the image. +- `run_id: string` -### Code Interpreter Tool Call +### Returns -- `CodeInterpreterToolCall object { id, code_interpreter, type }` +- `Run object { id, assistant_id, cancelled_at, 24 more }` - Details of the Code Interpreter tool call the run step was involved in. + Represents an execution run on a [thread](/docs/api-reference/threads). - `id: string` - The ID of the tool call. - - - `code_interpreter: object { input, outputs }` - - The Code Interpreter tool call definition. - - - `input: string` - - The input to the Code Interpreter tool call. - - - `outputs: array of object { logs, type } or object { image, type }` - - The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - - `CodeInterpreterLogOutput object { logs, type }` - - Text output from the Code Interpreter tool call as part of a run step. - - - `logs: string` - - The text output from the Code Interpreter tool call. + The identifier, which can be referenced in API endpoints. - - `type: "logs"` + - `assistant_id: string` - Always `logs`. + The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. - - `"logs"` + - `cancelled_at: number` - - `CodeInterpreterImageOutput object { image, type }` + The Unix timestamp (in seconds) for when the run was cancelled. - - `image: object { file_id }` + - `completed_at: number` - - `file_id: string` + The Unix timestamp (in seconds) for when the run was completed. - The [file](/docs/api-reference/files) ID of the image. + - `created_at: number` - - `type: "image"` + The Unix timestamp (in seconds) for when the run was created. - Always `image`. + - `expires_at: number` - - `"image"` + The Unix timestamp (in seconds) for when the run will expire. - - `type: "code_interpreter"` + - `failed_at: number` - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + The Unix timestamp (in seconds) for when the run failed. - - `"code_interpreter"` + - `incomplete_details: object { reason }` -### Code Interpreter Tool Call Delta + Details on why the run is incomplete. Will be `null` if the run is not incomplete. -- `CodeInterpreterToolCallDelta object { index, type, id, code_interpreter }` + - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` - Details of the Code Interpreter tool call the run step was involved in. + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `index: number` + - `"max_completion_tokens"` - The index of the tool call in the tool calls array. + - `"max_prompt_tokens"` - - `type: "code_interpreter"` + - `instructions: string` - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + The instructions that the [assistant](/docs/api-reference/assistants) used for this run. - - `"code_interpreter"` + - `last_error: object { code, message }` - - `id: optional string` + The last error associated with this run. Will be `null` if there are no errors. - The ID of the tool call. + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` - - `code_interpreter: optional object { input, outputs }` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - The Code Interpreter tool call definition. + - `"server_error"` - - `input: optional string` + - `"rate_limit_exceeded"` - The input to the Code Interpreter tool call. + - `"invalid_prompt"` - - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` + - `message: string` - The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. + A human-readable description of the error. - - `CodeInterpreterLogs object { index, type, logs }` + - `max_completion_tokens: number` - Text output from the Code Interpreter tool call as part of a run step. + The maximum number of completion tokens specified to have been used over the course of the run. - - `index: number` + - `max_prompt_tokens: number` - The index of the output in the outputs array. + The maximum number of prompt tokens specified to have been used over the course of the run. - - `type: "logs"` + - `metadata: Metadata` - Always `logs`. + 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. - - `"logs"` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `logs: optional string` + - `model: string` - The text output from the Code Interpreter tool call. + The model that the [assistant](/docs/api-reference/assistants) used for this run. - - `CodeInterpreterOutputImage object { index, type, image }` + - `object: "thread.run"` - - `index: number` + The object type, which is always `thread.run`. - The index of the output in the outputs array. + - `"thread.run"` - - `type: "image"` + - `parallel_tool_calls: boolean` - Always `image`. + Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `"image"` + - `required_action: object { submit_tool_outputs, type }` - - `image: optional object { file_id }` + Details on the action required to continue the run. Will be `null` if no action is required. - - `file_id: optional string` + - `submit_tool_outputs: object { tool_calls }` - The [file](/docs/api-reference/files) ID of the image. + Details on the tool outputs needed for this run to continue. -### File Search Tool Call + - `tool_calls: array of RequiredActionFunctionToolCall` -- `FileSearchToolCall object { id, file_search, type }` + A list of the relevant tool calls. - `id: string` - The ID of the tool call object. + The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](/docs/api-reference/runs/submitToolOutputs) endpoint. - - `file_search: object { ranking_options, results }` + - `function: object { arguments, name }` - For now, this is always going to be an empty object. + The function definition. - - `ranking_options: optional object { ranker, score_threshold }` + - `arguments: string` - The ranking options for the file search. + The arguments that the model expects you to pass to the function. - - `ranker: "auto" or "default_2024_08_21"` + - `name: string` - The ranker to use for the file search. If not specified will use the `auto` ranker. + The name of the function. - - `"auto"` + - `type: "function"` - - `"default_2024_08_21"` + The type of tool call the output is required for. For now, this is always `function`. - - `score_threshold: number` + - `"function"` - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `type: "submit_tool_outputs"` - - `results: optional array of object { file_id, file_name, score, content }` + For now, this is always `submit_tool_outputs`. - The results of the file search. + - `"submit_tool_outputs"` - - `file_id: string` + - `response_format: AssistantResponseFormatOption` - The ID of the file that result was found in. + Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `file_name: string` + Setting to `{ "type": "json_schema", "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 name of the file that result was found in. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `score: number` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - The score of the result. All values must be a floating point number between 0 and 1. + - `"auto"` - - `content: optional array of object { text, type }` + `auto` is the default value - The content of the result that was found. The content is only included if requested via the include query parameter. + - `"auto"` - - `text: optional string` + - `ResponseFormatText object { type }` - The text content of the file. + Default response format. Used to generate text responses. - - `type: optional "text"` + - `type: "text"` - The type of the content. + The type of response format being defined. Always `text`. - `"text"` - - `type: "file_search"` - - The type of tool call. This is always going to be `file_search` for this type of tool call. - - - `"file_search"` - -### File Search Tool Call Delta - -- `FileSearchToolCallDelta object { file_search, index, type, id }` - - - `file_search: unknown` - - For now, this is always going to be an empty object. - - - `index: number` - - The index of the tool call in the tool calls array. - - - `type: "file_search"` - - The type of tool call. This is always going to be `file_search` for this type of tool call. - - - `"file_search"` - - - `id: optional string` - - The ID of the tool call object. + - `ResponseFormatJSONObject object { type }` -### Function Tool Call + 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. -- `FunctionToolCall object { id, function, type }` + - `type: "json_object"` - - `id: string` + The type of response format being defined. Always `json_object`. - The ID of the tool call object. + - `"json_object"` - - `function: object { arguments, name, output }` + - `ResponseFormatJSONSchema object { json_schema, type }` - The definition of the function that was called. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `arguments: string` + - `json_schema: object { name, description, schema, strict }` - The arguments passed to the function. + Structured Outputs configuration options, including a JSON Schema. - `name: string` - The name of the function. - - - `output: string` - - The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. - - - `type: "function"` - - The type of tool call. This is always going to be `function` for this type of tool call. - - - `"function"` - -### Function Tool Call Delta - -- `FunctionToolCallDelta object { index, type, id, function }` - - - `index: number` - - The index of the tool call in the tool calls array. - - - `type: "function"` - - The type of tool call. This is always going to be `function` for this type of tool call. - - - `"function"` - - - `id: optional string` - - The ID of the tool call object. - - - `function: optional object { arguments, name, output }` - - The definition of the function that was called. - - - `arguments: optional string` - - The arguments passed to the function. - - - `name: optional string` - - The name of the function. - - - `output: optional 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 output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. + - `description: optional string` -### Message Creation Step Details + A description of what the response format is for, used by the model to + determine how to respond in the format. -- `MessageCreationStepDetails object { message_creation, type }` + - `schema: optional map[unknown]` - Details of the message creation by the run step. + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `message_creation: object { message_id }` + - `strict: optional boolean` - - `message_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 ID of the message that was created by this run step. + - `type: "json_schema"` - - `type: "message_creation"` + The type of response format being defined. Always `json_schema`. - Always `message_creation`. + - `"json_schema"` - - `"message_creation"` + - `started_at: number` -### Run Step + The Unix timestamp (in seconds) for when the run was started. -- `RunStep object { id, assistant_id, cancelled_at, 13 more }` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - Represents a step in execution of a run. + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `id: string` + - `"queued"` - The identifier of the run step, which can be referenced in API endpoints. + - `"in_progress"` - - `assistant_id: string` + - `"requires_action"` - The ID of the [assistant](/docs/api-reference/assistants) associated with the run step. + - `"cancelling"` - - `cancelled_at: number` + - `"cancelled"` - The Unix timestamp (in seconds) for when the run step was cancelled. + - `"failed"` - - `completed_at: number` + - `"completed"` - The Unix timestamp (in seconds) for when the run step completed. + - `"incomplete"` - - `created_at: number` + - `"expired"` - The Unix timestamp (in seconds) for when the run step was created. + - `thread_id: string` - - `expired_at: number` + The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. - The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + - `tool_choice: AssistantToolChoiceOption` - - `failed_at: number` + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - The Unix timestamp (in seconds) for when the run step failed. + - `"none" or "auto" or "required"` - - `last_error: object { code, message }` + `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. - The last error associated with this run step. Will be `null` if there are no errors. + - `"none"` - - `code: "server_error" or "rate_limit_exceeded"` + - `"auto"` - One of `server_error` or `rate_limit_exceeded`. + - `"required"` - - `"server_error"` + - `AssistantToolChoice object { type, function }` - - `"rate_limit_exceeded"` + Specifies a tool the model should use. Use to force the model to call a specific tool. - - `message: string` + - `type: "function" or "code_interpreter" or "file_search"` - A human-readable description of the error. + The type of the tool. If type is `function`, the function name must be set - - `metadata: Metadata` + - `"function"` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + - `"code_interpreter"` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"file_search"` - - `object: "thread.run.step"` + - `function: optional AssistantToolChoiceFunction` - The object type, which is always `thread.run.step`. + - `name: string` - - `"thread.run.step"` + The name of the function to call. - - `run_id: string` + - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` - The ID of the [run](/docs/api-reference/runs) that this run step is a part of. + The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. - - `status: "in_progress" or "cancelled" or "failed" or 2 more` + - `CodeInterpreterTool object { type }` - The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. + - `type: "code_interpreter"` - - `"in_progress"` + The type of tool being defined: `code_interpreter` - - `"cancelled"` + - `"code_interpreter"` - - `"failed"` + - `FileSearchTool object { type, file_search }` - - `"completed"` + - `type: "file_search"` - - `"expired"` + The type of tool being defined: `file_search` - - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` + - `"file_search"` - The details of the run step. + - `file_search: optional object { max_num_results, ranking_options }` - - `MessageCreationStepDetails object { message_creation, type }` + Overrides for the file search tool. - Details of the message creation by the run step. + - `max_num_results: optional number` - - `message_creation: object { message_id }` + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `message_id: string` + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - The ID of the message that was created by this run step. + - `ranking_options: optional object { score_threshold, ranker }` - - `type: "message_creation"` + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - Always `message_creation`. + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `"message_creation"` + - `score_threshold: number` - - `ToolCallsStepDetails object { tool_calls, type }` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - Details of the tool call. + - `ranker: optional "auto" or "default_2024_08_21"` - - `tool_calls: array of CodeInterpreterToolCall or FileSearchToolCall or FunctionToolCall` + The ranker to use for the file search. If not specified will use the `auto` ranker. - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + - `"auto"` - - `CodeInterpreterToolCall object { id, code_interpreter, type }` + - `"default_2024_08_21"` - Details of the Code Interpreter tool call the run step was involved in. + - `FunctionTool object { function, type }` - - `id: string` + - `function: FunctionDefinition` - The ID of the tool call. + - `name: string` - - `code_interpreter: object { input, outputs }` + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - The Code Interpreter tool call definition. + - `description: optional string` - - `input: string` + A description of what the function does, used by the model to choose when and how to call the function. - The input to the Code Interpreter tool call. + - `parameters: optional FunctionParameters` - - `outputs: array of object { logs, type } or object { image, type }` + The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. + Omitting `parameters` defines a function with an empty parameter list. - - `CodeInterpreterLogOutput object { logs, type }` + - `strict: optional boolean` - Text output from the Code Interpreter tool call as part of a run step. + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-calling). - - `logs: string` + - `type: "function"` - The text output from the Code Interpreter tool call. + The type of tool being defined: `function` - - `type: "logs"` + - `"function"` - Always `logs`. + - `truncation_strategy: object { type, last_messages }` - - `"logs"` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `CodeInterpreterImageOutput object { image, type }` + - `type: "auto" or "last_messages"` - - `image: object { file_id }` + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. - - `file_id: string` + - `"auto"` - The [file](/docs/api-reference/files) ID of the image. + - `"last_messages"` - - `type: "image"` + - `last_messages: optional number` - Always `image`. + The number of most recent messages from the thread when constructing the context for the run. - - `"image"` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `type: "code_interpreter"` + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + - `completion_tokens: number` - - `"code_interpreter"` + Number of completion tokens used over the course of the run. - - `FileSearchToolCall object { id, file_search, type }` + - `prompt_tokens: number` - - `id: string` + Number of prompt tokens used over the course of the run. - The ID of the tool call object. + - `total_tokens: number` - - `file_search: object { ranking_options, results }` + Total number of tokens used (prompt + completion). - For now, this is always going to be an empty object. + - `temperature: optional number` - - `ranking_options: optional object { ranker, score_threshold }` + The sampling temperature used for this run. If not set, defaults to 1. - The ranking options for the file search. + - `top_p: optional number` - - `ranker: "auto" or "default_2024_08_21"` + The nucleus sampling value used for this run. If not set, defaults to 1. - The ranker to use for the file search. If not specified will use the `auto` ranker. +### Example - - `"auto"` +```http +curl https://api.openai.com/v1/threads/$THREAD_ID/runs/$RUN_ID \ + -H 'OpenAI-Beta: assistants=v2' \ + -H "Authorization: Bearer $OPENAI_API_KEY" +``` - - `"default_2024_08_21"` +#### Response - - `score_threshold: number` +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expires_at": 0, + "failed_at": 0, + "incomplete_details": { + "reason": "max_completion_tokens" + }, + "instructions": "instructions", + "last_error": { + "code": "server_error", + "message": "message" + }, + "max_completion_tokens": 256, + "max_prompt_tokens": 256, + "metadata": { + "foo": "string" + }, + "model": "model", + "object": "thread.run", + "parallel_tool_calls": true, + "required_action": { + "submit_tool_outputs": { + "tool_calls": [ + { + "id": "id", + "function": { + "arguments": "arguments", + "name": "name" + }, + "type": "function" + } + ] + }, + "type": "submit_tool_outputs" + }, + "response_format": "auto", + "started_at": 0, + "status": "queued", + "thread_id": "thread_id", + "tool_choice": "none", + "tools": [ + { + "type": "code_interpreter" + } + ], + "truncation_strategy": { + "type": "auto", + "last_messages": 1 + }, + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + }, + "temperature": 0, + "top_p": 0 +} +``` - The score threshold for the file search. All values must be a floating point number between 0 and 1. +### Example - - `results: optional array of object { file_id, file_name, score, content }` +```http +curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "OpenAI-Beta: assistants=v2" +``` - The results of the file search. +#### Response - - `file_id: string` +```json +{ + "id": "run_abc123", + "object": "thread.run", + "created_at": 1699075072, + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "status": "completed", + "started_at": 1699075072, + "expires_at": null, + "cancelled_at": null, + "failed_at": null, + "completed_at": 1699075073, + "last_error": null, + "model": "gpt-4o", + "instructions": null, + "incomplete_details": null, + "tools": [ + { + "type": "code_interpreter" + } + ], + "metadata": {}, + "usage": { + "prompt_tokens": 123, + "completion_tokens": 456, + "total_tokens": 579 + }, + "temperature": 1.0, + "top_p": 1.0, + "max_prompt_tokens": 1000, + "max_completion_tokens": 1000, + "truncation_strategy": { + "type": "auto", + "last_messages": null + }, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true +} +``` - The ID of the file that result was found in. +## Submit tool outputs to run - - `file_name: string` +**post** `/threads/{thread_id}/runs/{run_id}/submit_tool_outputs` - The name of the file that result was found in. +When a run has the `status: "requires_action"` and `required_action.type` is `submit_tool_outputs`, this endpoint can be used to submit the outputs from the tool calls once they're all completed. All outputs must be submitted in a single request. - - `score: number` +### Path Parameters - The score of the result. All values must be a floating point number between 0 and 1. +- `thread_id: string` - - `content: optional array of object { text, type }` +- `run_id: string` - The content of the result that was found. The content is only included if requested via the include query parameter. +### Body Parameters - - `text: optional string` +- `tool_outputs: array of object { output, tool_call_id }` - The text content of the file. + A list of tools for which the outputs are being submitted. - - `type: optional "text"` + - `output: optional string` - The type of the content. + The output of the tool call to be submitted to continue the run. - - `"text"` + - `tool_call_id: optional string` - - `type: "file_search"` + The ID of the tool call in the `required_action` object within the run object the output is being submitted for. - The type of tool call. This is always going to be `file_search` for this type of tool call. +- `stream: optional boolean` - - `"file_search"` + If `true`, returns a stream of events that happen during the Run as server-sent events, terminating when the Run enters a terminal state with a `data: [DONE]` message. - - `FunctionToolCall object { id, function, type }` +### Returns - - `id: string` +- `Run object { id, assistant_id, cancelled_at, 24 more }` - The ID of the tool call object. + Represents an execution run on a [thread](/docs/api-reference/threads). - - `function: object { arguments, name, output }` + - `id: string` - The definition of the function that was called. + The identifier, which can be referenced in API endpoints. - - `arguments: string` + - `assistant_id: string` - The arguments passed to the function. + The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. - - `name: string` + - `cancelled_at: number` - The name of the function. + The Unix timestamp (in seconds) for when the run was cancelled. - - `output: string` + - `completed_at: number` - The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. + The Unix timestamp (in seconds) for when the run was completed. - - `type: "function"` + - `created_at: number` - The type of tool call. This is always going to be `function` for this type of tool call. + The Unix timestamp (in seconds) for when the run was created. - - `"function"` + - `expires_at: number` - - `type: "tool_calls"` + The Unix timestamp (in seconds) for when the run will expire. - Always `tool_calls`. + - `failed_at: number` - - `"tool_calls"` + The Unix timestamp (in seconds) for when the run failed. - - `thread_id: string` + - `incomplete_details: object { reason }` - The ID of the [thread](/docs/api-reference/threads) that was run. + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `type: "message_creation" or "tool_calls"` + - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` - The type of run step, which can be either `message_creation` or `tool_calls`. + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `"message_creation"` + - `"max_completion_tokens"` - - `"tool_calls"` + - `"max_prompt_tokens"` - - `usage: object { completion_tokens, prompt_tokens, total_tokens }` + - `instructions: string` - Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. + The instructions that the [assistant](/docs/api-reference/assistants) used for this run. - - `completion_tokens: number` + - `last_error: object { code, message }` - Number of completion tokens used over the course of the run step. + The last error associated with this run. Will be `null` if there are no errors. - - `prompt_tokens: number` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` - Number of prompt tokens used over the course of the run step. + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `total_tokens: number` + - `"server_error"` - Total number of tokens used (prompt + completion). + - `"rate_limit_exceeded"` -### Run Step Delta Event + - `"invalid_prompt"` -- `RunStepDeltaEvent object { id, delta, object }` + - `message: string` - Represents a run step delta i.e. any changed fields on a run step during streaming. + A human-readable description of the error. - - `id: string` + - `max_completion_tokens: number` - The identifier of the run step, which can be referenced in API endpoints. + The maximum number of completion tokens specified to have been used over the course of the run. - - `delta: object { step_details }` + - `max_prompt_tokens: number` - The delta containing the fields that have changed on the run step. + The maximum number of prompt tokens specified to have been used over the course of the run. - - `step_details: optional RunStepDeltaMessageDelta or ToolCallDeltaObject` + - `metadata: Metadata` - The details of the run step. + 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. - - `RunStepDeltaMessageDelta object { type, message_creation }` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - Details of the message creation by the run step. + - `model: string` - - `type: "message_creation"` + The model that the [assistant](/docs/api-reference/assistants) used for this run. - Always `message_creation`. + - `object: "thread.run"` - - `"message_creation"` + The object type, which is always `thread.run`. - - `message_creation: optional object { message_id }` + - `"thread.run"` - - `message_id: optional string` + - `parallel_tool_calls: boolean` - The ID of the message that was created by this run step. + Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. - - `ToolCallDeltaObject object { type, tool_calls }` + - `required_action: object { submit_tool_outputs, type }` - Details of the tool call. + Details on the action required to continue the run. Will be `null` if no action is required. - - `type: "tool_calls"` + - `submit_tool_outputs: object { tool_calls }` - Always `tool_calls`. + Details on the tool outputs needed for this run to continue. - - `"tool_calls"` + - `tool_calls: array of RequiredActionFunctionToolCall` - - `tool_calls: optional array of CodeInterpreterToolCallDelta or FileSearchToolCallDelta or FunctionToolCallDelta` + A list of the relevant tool calls. - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + - `id: string` - - `CodeInterpreterToolCallDelta object { index, type, id, code_interpreter }` + The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](/docs/api-reference/runs/submitToolOutputs) endpoint. - Details of the Code Interpreter tool call the run step was involved in. + - `function: object { arguments, name }` - - `index: number` + The function definition. - The index of the tool call in the tool calls array. + - `arguments: string` - - `type: "code_interpreter"` + The arguments that the model expects you to pass to the function. - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + - `name: string` - - `"code_interpreter"` + The name of the function. - - `id: optional string` + - `type: "function"` - The ID of the tool call. + The type of tool call the output is required for. For now, this is always `function`. - - `code_interpreter: optional object { input, outputs }` + - `"function"` - The Code Interpreter tool call definition. + - `type: "submit_tool_outputs"` - - `input: optional string` + For now, this is always `submit_tool_outputs`. - The input to the Code Interpreter tool call. + - `"submit_tool_outputs"` - - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` + - `response_format: AssistantResponseFormatOption` - The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. + Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `CodeInterpreterLogs object { index, type, logs }` + Setting to `{ "type": "json_schema", "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). - Text output from the Code Interpreter tool call as part of a run step. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `index: number` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - The index of the output in the outputs array. + - `"auto"` - - `type: "logs"` + `auto` is the default value - Always `logs`. + - `"auto"` - - `"logs"` + - `ResponseFormatText object { type }` - - `logs: optional string` + Default response format. Used to generate text responses. - The text output from the Code Interpreter tool call. + - `type: "text"` - - `CodeInterpreterOutputImage object { index, type, image }` + The type of response format being defined. Always `text`. - - `index: number` + - `"text"` - The index of the output in the outputs array. + - `ResponseFormatJSONObject object { type }` - - `type: "image"` + 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. - Always `image`. + - `type: "json_object"` - - `"image"` + The type of response format being defined. Always `json_object`. - - `image: optional object { file_id }` + - `"json_object"` - - `file_id: optional string` + - `ResponseFormatJSONSchema object { json_schema, type }` - The [file](/docs/api-reference/files) ID of the image. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `FileSearchToolCallDelta object { file_search, index, type, id }` + - `json_schema: object { name, description, schema, strict }` - - `file_search: unknown` + Structured Outputs configuration options, including a JSON Schema. - For now, this is always going to be an empty object. + - `name: string` - - `index: number` + 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 index of the tool call in the tool calls array. + - `description: optional string` - - `type: "file_search"` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The type of tool call. This is always going to be `file_search` for this type of tool call. + - `schema: optional map[unknown]` - - `"file_search"` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - - `id: optional string` + - `strict: optional boolean` - The ID of the tool call object. + 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). - - `FunctionToolCallDelta object { index, type, id, function }` + - `type: "json_schema"` - - `index: number` + The type of response format being defined. Always `json_schema`. - The index of the tool call in the tool calls array. + - `"json_schema"` - - `type: "function"` + - `started_at: number` - The type of tool call. This is always going to be `function` for this type of tool call. + The Unix timestamp (in seconds) for when the run was started. - - `"function"` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - - `id: optional string` + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - The ID of the tool call object. + - `"queued"` - - `function: optional object { arguments, name, output }` + - `"in_progress"` - The definition of the function that was called. + - `"requires_action"` - - `arguments: optional string` + - `"cancelling"` - The arguments passed to the function. + - `"cancelled"` - - `name: optional string` + - `"failed"` - The name of the function. + - `"completed"` - - `output: optional string` + - `"incomplete"` - The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. + - `"expired"` - - `object: "thread.run.step.delta"` + - `thread_id: string` - The object type, which is always `thread.run.step.delta`. + The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. - - `"thread.run.step.delta"` + - `tool_choice: AssistantToolChoiceOption` -### Run Step Delta Message Delta + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. -- `RunStepDeltaMessageDelta object { type, message_creation }` + - `"none" or "auto" or "required"` - Details of the message creation by the run step. + `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. - - `type: "message_creation"` + - `"none"` - Always `message_creation`. + - `"auto"` - - `"message_creation"` + - `"required"` - - `message_creation: optional object { message_id }` + - `AssistantToolChoice object { type, function }` - - `message_id: optional string` + Specifies a tool the model should use. Use to force the model to call a specific tool. - The ID of the message that was created by this run step. + - `type: "function" or "code_interpreter" or "file_search"` -### Run Step Include + The type of the tool. If type is `function`, the function name must be set -- `RunStepInclude = "step_details.tool_calls[*].file_search.results[*].content"` + - `"function"` - - `"step_details.tool_calls[*].file_search.results[*].content"` + - `"code_interpreter"` -### Tool Call Delta Object + - `"file_search"` -- `ToolCallDeltaObject object { type, tool_calls }` + - `function: optional AssistantToolChoiceFunction` - Details of the tool call. + - `name: string` - - `type: "tool_calls"` + The name of the function to call. - Always `tool_calls`. + - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` - - `"tool_calls"` + The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. - - `tool_calls: optional array of CodeInterpreterToolCallDelta or FileSearchToolCallDelta or FunctionToolCallDelta` + - `CodeInterpreterTool object { type }` - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. + - `type: "code_interpreter"` - - `CodeInterpreterToolCallDelta object { index, type, id, code_interpreter }` + The type of tool being defined: `code_interpreter` - Details of the Code Interpreter tool call the run step was involved in. + - `"code_interpreter"` - - `index: number` + - `FileSearchTool object { type, file_search }` - The index of the tool call in the tool calls array. + - `type: "file_search"` - - `type: "code_interpreter"` + The type of tool being defined: `file_search` - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. + - `"file_search"` - - `"code_interpreter"` + - `file_search: optional object { max_num_results, ranking_options }` - - `id: optional string` + Overrides for the file search tool. - The ID of the tool call. + - `max_num_results: optional number` - - `code_interpreter: optional object { input, outputs }` + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - The Code Interpreter tool call definition. + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `input: optional string` + - `ranking_options: optional object { score_threshold, ranker }` - The input to the Code Interpreter tool call. + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. + - `score_threshold: number` - - `CodeInterpreterLogs object { index, type, logs }` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - Text output from the Code Interpreter tool call as part of a run step. + - `ranker: optional "auto" or "default_2024_08_21"` - - `index: number` + The ranker to use for the file search. If not specified will use the `auto` ranker. - The index of the output in the outputs array. + - `"auto"` - - `type: "logs"` + - `"default_2024_08_21"` - Always `logs`. + - `FunctionTool object { function, type }` - - `"logs"` + - `function: FunctionDefinition` - - `logs: optional string` + - `name: string` - The text output from the Code Interpreter tool call. + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `CodeInterpreterOutputImage object { index, type, image }` + - `description: optional string` - - `index: number` + A description of what the function does, used by the model to choose when and how to call the function. - The index of the output in the outputs array. + - `parameters: optional FunctionParameters` - - `type: "image"` + The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - Always `image`. + Omitting `parameters` defines a function with an empty parameter list. - - `"image"` + - `strict: optional boolean` - - `image: optional object { file_id }` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-calling). - - `file_id: optional string` + - `type: "function"` - The [file](/docs/api-reference/files) ID of the image. + The type of tool being defined: `function` - - `FileSearchToolCallDelta object { file_search, index, type, id }` + - `"function"` - - `file_search: unknown` + - `truncation_strategy: object { type, last_messages }` - For now, this is always going to be an empty object. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `index: number` + - `type: "auto" or "last_messages"` - The index of the tool call in the tool calls array. + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. - - `type: "file_search"` + - `"auto"` - The type of tool call. This is always going to be `file_search` for this type of tool call. + - `"last_messages"` - - `"file_search"` + - `last_messages: optional number` - - `id: optional string` + The number of most recent messages from the thread when constructing the context for the run. - The ID of the tool call object. + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `FunctionToolCallDelta object { index, type, id, function }` + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - - `index: number` + - `completion_tokens: number` - The index of the tool call in the tool calls array. + Number of completion tokens used over the course of the run. - - `type: "function"` + - `prompt_tokens: number` - The type of tool call. This is always going to be `function` for this type of tool call. + Number of prompt tokens used over the course of the run. - - `"function"` + - `total_tokens: number` - - `id: optional string` + Total number of tokens used (prompt + completion). - The ID of the tool call object. + - `temperature: optional number` - - `function: optional object { arguments, name, output }` + The sampling temperature used for this run. If not set, defaults to 1. - The definition of the function that was called. + - `top_p: optional number` - - `arguments: optional string` + The nucleus sampling value used for this run. If not set, defaults to 1. - The arguments passed to the function. +### Example - - `name: optional string` +```http +curl https://api.openai.com/v1/threads/$THREAD_ID/runs/$RUN_ID/submit_tool_outputs \ + -H 'Content-Type: application/json' \ + -H 'OpenAI-Beta: assistants=v2' \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{ + "tool_outputs": [ + {} + ] + }' +``` - The name of the function. +#### Response - - `output: optional string` +```json +{ + "id": "id", + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expires_at": 0, + "failed_at": 0, + "incomplete_details": { + "reason": "max_completion_tokens" + }, + "instructions": "instructions", + "last_error": { + "code": "server_error", + "message": "message" + }, + "max_completion_tokens": 256, + "max_prompt_tokens": 256, + "metadata": { + "foo": "string" + }, + "model": "model", + "object": "thread.run", + "parallel_tool_calls": true, + "required_action": { + "submit_tool_outputs": { + "tool_calls": [ + { + "id": "id", + "function": { + "arguments": "arguments", + "name": "name" + }, + "type": "function" + } + ] + }, + "type": "submit_tool_outputs" + }, + "response_format": "auto", + "started_at": 0, + "status": "queued", + "thread_id": "thread_id", + "tool_choice": "none", + "tools": [ + { + "type": "code_interpreter" + } + ], + "truncation_strategy": { + "type": "auto", + "last_messages": 1 + }, + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + }, + "temperature": 0, + "top_p": 0 +} +``` - The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. +### Example -### Tool Calls Step Details +```http +curl https://api.openai.com/v1/threads/thread_123/runs/run_123/submit_tool_outputs \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "tool_outputs": [ + { + "tool_call_id": "call_001", + "output": "70 degrees and sunny." + } + ] + }' +``` -- `ToolCallsStepDetails object { tool_calls, type }` +#### Response - Details of the tool call. +```json +{ + "id": "run_123", + "object": "thread.run", + "created_at": 1699075592, + "assistant_id": "asst_123", + "thread_id": "thread_123", + "status": "queued", + "started_at": 1699075592, + "expires_at": 1699076192, + "cancelled_at": null, + "failed_at": null, + "completed_at": null, + "last_error": null, + "model": "gpt-4o", + "instructions": null, + "tools": [ + { + "type": "function", + "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"] + } + } + } + ], + "metadata": {}, + "usage": null, + "temperature": 1.0, + "top_p": 1.0, + "max_prompt_tokens": 1000, + "max_completion_tokens": 1000, + "truncation_strategy": { + "type": "auto", + "last_messages": null + }, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true +} +``` - - `tool_calls: array of CodeInterpreterToolCall or FileSearchToolCall or FunctionToolCall` +### Streaming - An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. +```http +curl https://api.openai.com/v1/threads/thread_123/runs/run_123/submit_tool_outputs \ + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "tool_outputs": [ + { + "tool_call_id": "call_001", + "output": "70 degrees and sunny." + } + ], + "stream": true + }' +``` - - `CodeInterpreterToolCall object { id, code_interpreter, type }` +#### Response - Details of the Code Interpreter tool call the run step was involved in. +```json +event: thread.run.step.completed +data: {"id":"step_001","object":"thread.run.step","created_at":1710352449,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"tool_calls","status":"completed","cancelled_at":null,"completed_at":1710352475,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"tool_calls","tool_calls":[{"id":"call_iWr0kQ2EaYMaxNdl0v3KYkx7","type":"function","function":{"name":"get_current_weather","arguments":"{\"location\":\"San Francisco, CA\",\"unit\":\"fahrenheit\"}","output":"70 degrees and sunny."}}]},"usage":{"prompt_tokens":291,"completion_tokens":24,"total_tokens":315}} - - `id: string` +event: thread.run.queued +data: {"id":"run_123","object":"thread.run","created_at":1710352447,"assistant_id":"asst_123","thread_id":"thread_123","status":"queued","started_at":1710352448,"expires_at":1710353047,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","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"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - The ID of the tool call. +event: thread.run.in_progress +data: {"id":"run_123","object":"thread.run","created_at":1710352447,"assistant_id":"asst_123","thread_id":"thread_123","status":"in_progress","started_at":1710352475,"expires_at":1710353047,"cancelled_at":null,"failed_at":null,"completed_at":null,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","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"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":null,"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - - `code_interpreter: object { input, outputs }` +event: thread.run.step.created +data: {"id":"step_002","object":"thread.run.step","created_at":1710352476,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_002"}},"usage":null} - The Code Interpreter tool call definition. +event: thread.run.step.in_progress +data: {"id":"step_002","object":"thread.run.step","created_at":1710352476,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"in_progress","cancelled_at":null,"completed_at":null,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_002"}},"usage":null} - - `input: string` +event: thread.message.created +data: {"id":"msg_002","object":"thread.message","created_at":1710352476,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} - The input to the Code Interpreter tool call. +event: thread.message.in_progress +data: {"id":"msg_002","object":"thread.message","created_at":1710352476,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"in_progress","incomplete_details":null,"incomplete_at":null,"completed_at":null,"role":"assistant","content":[],"metadata":{}} - - `outputs: array of object { logs, type } or object { image, type }` +event: thread.message.delta +data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"The","annotations":[]}}]}} - The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. +event: thread.message.delta +data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" current"}}]}} - - `CodeInterpreterLogOutput object { logs, type }` +event: thread.message.delta +data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" weather"}}]}} - Text output from the Code Interpreter tool call as part of a run step. +... - - `logs: string` +event: thread.message.delta +data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":" sunny"}}]}} - The text output from the Code Interpreter tool call. +event: thread.message.delta +data: {"id":"msg_002","object":"thread.message.delta","delta":{"content":[{"index":0,"type":"text","text":{"value":"."}}]}} - - `type: "logs"` +event: thread.message.completed +data: {"id":"msg_002","object":"thread.message","created_at":1710352476,"assistant_id":"asst_123","thread_id":"thread_123","run_id":"run_123","status":"completed","incomplete_details":null,"incomplete_at":null,"completed_at":1710352477,"role":"assistant","content":[{"type":"text","text":{"value":"The current weather in San Francisco, CA is 70 degrees Fahrenheit and sunny.","annotations":[]}}],"metadata":{}} - Always `logs`. +event: thread.run.step.completed +data: {"id":"step_002","object":"thread.run.step","created_at":1710352476,"run_id":"run_123","assistant_id":"asst_123","thread_id":"thread_123","type":"message_creation","status":"completed","cancelled_at":null,"completed_at":1710352477,"expires_at":1710353047,"failed_at":null,"last_error":null,"step_details":{"type":"message_creation","message_creation":{"message_id":"msg_002"}},"usage":{"prompt_tokens":329,"completion_tokens":18,"total_tokens":347}} - - `"logs"` +event: thread.run.completed +data: {"id":"run_123","object":"thread.run","created_at":1710352447,"assistant_id":"asst_123","thread_id":"thread_123","status":"completed","started_at":1710352475,"expires_at":null,"cancelled_at":null,"failed_at":null,"completed_at":1710352477,"required_action":null,"last_error":null,"model":"gpt-4o","instructions":null,"tools":[{"type":"function","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"]}}}],"metadata":{},"temperature":1.0,"top_p":1.0,"max_completion_tokens":null,"max_prompt_tokens":null,"truncation_strategy":{"type":"auto","last_messages":null},"incomplete_details":null,"usage":{"prompt_tokens":20,"completion_tokens":11,"total_tokens":31},"response_format":"auto","tool_choice":"auto","parallel_tool_calls":true}} - - `CodeInterpreterImageOutput object { image, type }` +event: done +data: [DONE] +``` - - `image: object { file_id }` +## Modify run - - `file_id: string` +**post** `/threads/{thread_id}/runs/{run_id}` - The [file](/docs/api-reference/files) ID of the image. +Modifies a run. - - `type: "image"` +### Path Parameters - Always `image`. +- `thread_id: string` - - `"image"` +- `run_id: string` - - `type: "code_interpreter"` +### Body Parameters - The type of tool call. This is always going to be `code_interpreter` for this type of tool call. +- `metadata: optional Metadata` - - `"code_interpreter"` + 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. - - `FileSearchToolCall object { id, file_search, type }` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `id: string` +### Returns - The ID of the tool call object. +- `Run object { id, assistant_id, cancelled_at, 24 more }` - - `file_search: object { ranking_options, results }` + Represents an execution run on a [thread](/docs/api-reference/threads). - For now, this is always going to be an empty object. + - `id: string` - - `ranking_options: optional object { ranker, score_threshold }` + The identifier, which can be referenced in API endpoints. - The ranking options for the file search. + - `assistant_id: string` - - `ranker: "auto" or "default_2024_08_21"` + The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. - The ranker to use for the file search. If not specified will use the `auto` ranker. + - `cancelled_at: number` - - `"auto"` + The Unix timestamp (in seconds) for when the run was cancelled. - - `"default_2024_08_21"` + - `completed_at: number` - - `score_threshold: number` + The Unix timestamp (in seconds) for when the run was completed. - The score threshold for the file search. All values must be a floating point number between 0 and 1. + - `created_at: number` - - `results: optional array of object { file_id, file_name, score, content }` + The Unix timestamp (in seconds) for when the run was created. - The results of the file search. + - `expires_at: number` - - `file_id: string` + The Unix timestamp (in seconds) for when the run will expire. - The ID of the file that result was found in. + - `failed_at: number` - - `file_name: string` + The Unix timestamp (in seconds) for when the run failed. - The name of the file that result was found in. + - `incomplete_details: object { reason }` - - `score: number` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - The score of the result. All values must be a floating point number between 0 and 1. + - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` - - `content: optional array of object { text, type }` + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - The content of the result that was found. The content is only included if requested via the include query parameter. + - `"max_completion_tokens"` - - `text: optional string` + - `"max_prompt_tokens"` - The text content of the file. + - `instructions: string` - - `type: optional "text"` + The instructions that the [assistant](/docs/api-reference/assistants) used for this run. - The type of the content. + - `last_error: object { code, message }` - - `"text"` + The last error associated with this run. Will be `null` if there are no errors. - - `type: "file_search"` + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` - The type of tool call. This is always going to be `file_search` for this type of tool call. + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. - - `"file_search"` + - `"server_error"` - - `FunctionToolCall object { id, function, type }` + - `"rate_limit_exceeded"` - - `id: string` + - `"invalid_prompt"` - The ID of the tool call object. + - `message: string` - - `function: object { arguments, name, output }` + A human-readable description of the error. - The definition of the function that was called. + - `max_completion_tokens: number` - - `arguments: string` + The maximum number of completion tokens specified to have been used over the course of the run. - The arguments passed to the function. + - `max_prompt_tokens: number` - - `name: string` + The maximum number of prompt tokens specified to have been used over the course of the run. - The name of the function. + - `metadata: Metadata` - - `output: 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 output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `type: "function"` + - `model: string` - The type of tool call. This is always going to be `function` for this type of tool call. + The model that the [assistant](/docs/api-reference/assistants) used for this run. - - `"function"` + - `object: "thread.run"` - - `type: "tool_calls"` + The object type, which is always `thread.run`. - Always `tool_calls`. + - `"thread.run"` - - `"tool_calls"` + - `parallel_tool_calls: boolean` -# Messages + Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. -## List messages + - `required_action: object { submit_tool_outputs, type }` -**get** `/threads/{thread_id}/messages` + Details on the action required to continue the run. Will be `null` if no action is required. -Returns a list of messages for a given thread. + - `submit_tool_outputs: object { tool_calls }` -### Path Parameters + Details on the tool outputs needed for this run to continue. -- `thread_id: string` + - `tool_calls: array of RequiredActionFunctionToolCall` -### Query Parameters + A list of the relevant tool calls. -- `after: optional string` + - `id: string` - A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. + The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](/docs/api-reference/runs/submitToolOutputs) endpoint. -- `before: optional string` + - `function: object { arguments, name }` - A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. + The function definition. -- `limit: optional number` + - `arguments: string` - A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + The arguments that the model expects you to pass to the function. -- `order: optional "asc" or "desc"` + - `name: string` - Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. + The name of the function. - - `"asc"` + - `type: "function"` - - `"desc"` + The type of tool call the output is required for. For now, this is always `function`. -- `run_id: optional string` + - `"function"` - Filter messages by the run ID that generated them. + - `type: "submit_tool_outputs"` -### Returns + For now, this is always `submit_tool_outputs`. -- `data: array of Message` + - `"submit_tool_outputs"` - - `id: string` + - `response_format: AssistantResponseFormatOption` - The identifier, which can be referenced in API endpoints. + Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - - `assistant_id: string` + Setting to `{ "type": "json_schema", "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). - If applicable, the ID of the [assistant](/docs/api-reference/assistants) that authored this message. + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `attachments: array of object { file_id, tools }` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - A list of files attached to the message, and the tools they were added to. + - `"auto"` - - `file_id: optional string` + `auto` is the default value - The ID of the file to attach to the message. + - `"auto"` - - `tools: optional array of CodeInterpreterTool or object { type }` + - `ResponseFormatText object { type }` - The tools to add this file to. + Default response format. Used to generate text responses. - - `CodeInterpreterTool object { type }` + - `type: "text"` - - `type: "code_interpreter"` + The type of response format being defined. Always `text`. - The type of tool being defined: `code_interpreter` + - `"text"` - - `"code_interpreter"` + - `ResponseFormatJSONObject object { type }` - - `FileSearchTool 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: "file_search"` + - `type: "json_object"` - The type of tool being defined: `file_search` + The type of response format being defined. Always `json_object`. - - `"file_search"` + - `"json_object"` - - `completed_at: number` + - `ResponseFormatJSONSchema object { json_schema, type }` - The Unix timestamp (in seconds) for when the message was completed. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `content: array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlock or RefusalContentBlock` + - `json_schema: object { name, description, schema, strict }` - The content of the message in array of text and/or images. + Structured Outputs configuration options, including a JSON Schema. - - `ImageFileContentBlock object { image_file, type }` + - `name: string` - References an image [File](/docs/api-reference/files) in the content of a message. + 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. - - `image_file: ImageFile` + - `description: optional string` - - `file_id: string` + A description of what the response format is for, used by the model to + determine how to respond in the format. - The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + - `schema: optional map[unknown]` - - `detail: optional "auto" or "low" or "high"` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `strict: optional boolean` - - `"auto"` + 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). - - `"low"` + - `type: "json_schema"` - - `"high"` + The type of response format being defined. Always `json_schema`. - - `type: "image_file"` + - `"json_schema"` - Always `image_file`. + - `started_at: number` - - `"image_file"` + The Unix timestamp (in seconds) for when the run was started. - - `ImageURLContentBlock object { image_url, type }` + - `status: "queued" or "in_progress" or "requires_action" or 6 more` - References an image URL in the content of a message. + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. - - `image_url: ImageURL` + - `"queued"` - - `url: string` + - `"in_progress"` - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `"requires_action"` - - `detail: optional "auto" or "low" or "high"` + - `"cancelling"` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `"cancelled"` - - `"auto"` + - `"failed"` - - `"low"` + - `"completed"` - - `"high"` + - `"incomplete"` - - `type: "image_url"` + - `"expired"` - The type of the content part. + - `thread_id: string` - - `"image_url"` + The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. - - `TextContentBlock object { text, type }` + - `tool_choice: AssistantToolChoiceOption` - The text content that is part of a message. + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. - - `text: Text` + - `"none" or "auto" or "required"` - - `annotations: array of FileCitationAnnotation or FilePathAnnotation` + `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. - - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` + - `"none"` - A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + - `"auto"` - - `end_index: number` + - `"required"` - - `file_citation: object { file_id }` + - `AssistantToolChoice object { type, function }` - - `file_id: string` + Specifies a tool the model should use. Use to force the model to call a specific tool. - The ID of the specific File the citation is from. + - `type: "function" or "code_interpreter" or "file_search"` - - `start_index: number` + The type of the tool. If type is `function`, the function name must be set - - `text: string` + - `"function"` - The text in the message content that needs to be replaced. + - `"code_interpreter"` - - `type: "file_citation"` + - `"file_search"` - Always `file_citation`. + - `function: optional AssistantToolChoiceFunction` - - `"file_citation"` + - `name: string` - - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` + The name of the function to call. - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` - - `end_index: number` + The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. - - `file_path: object { file_id }` + - `CodeInterpreterTool object { type }` - - `file_id: string` + - `type: "code_interpreter"` - The ID of the file that was generated. + The type of tool being defined: `code_interpreter` - - `start_index: number` + - `"code_interpreter"` - - `text: string` + - `FileSearchTool object { type, file_search }` - The text in the message content that needs to be replaced. + - `type: "file_search"` - - `type: "file_path"` + The type of tool being defined: `file_search` - Always `file_path`. + - `"file_search"` - - `"file_path"` + - `file_search: optional object { max_num_results, ranking_options }` - - `value: string` + Overrides for the file search tool. - The data that makes up the text. + - `max_num_results: optional number` - - `type: "text"` + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - Always `text`. + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `"text"` + - `ranking_options: optional object { score_threshold, ranker }` - - `RefusalContentBlock object { refusal, type }` + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - The refusal content generated by the assistant. + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - - `refusal: string` + - `score_threshold: number` - - `type: "refusal"` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - Always `refusal`. + - `ranker: optional "auto" or "default_2024_08_21"` - - `"refusal"` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `created_at: number` + - `"auto"` - The Unix timestamp (in seconds) for when the message was created. + - `"default_2024_08_21"` - - `incomplete_at: number` + - `FunctionTool object { function, type }` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + - `function: FunctionDefinition` - - `incomplete_details: object { reason }` + - `name: string` - On an incomplete message, details about why the message is incomplete. + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` + - `description: optional string` - The reason the message is incomplete. + A description of what the function does, used by the model to choose when and how to call the function. - - `"content_filter"` + - `parameters: optional FunctionParameters` - - `"max_tokens"` + The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - `"run_cancelled"` + Omitting `parameters` defines a function with an empty parameter list. - - `"run_expired"` + - `strict: optional boolean` - - `"run_failed"` + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-calling). - - `metadata: Metadata` + - `type: "function"` - Set of 16 key-value pairs that can be attached to an object. This can be - useful for storing additional information about the object in a structured - format, and querying for objects via API or the dashboard. + The type of tool being defined: `function` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `"function"` - - `object: "thread.message"` + - `truncation_strategy: object { type, last_messages }` - The object type, which is always `thread.message`. + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - - `"thread.message"` + - `type: "auto" or "last_messages"` - - `role: "user" or "assistant"` + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. - The entity that produced the message. One of `user` or `assistant`. + - `"auto"` - - `"user"` + - `"last_messages"` - - `"assistant"` + - `last_messages: optional number` - - `run_id: string` + The number of most recent messages from the thread when constructing the context for the run. - The ID of the [run](/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `status: "in_progress" or "incomplete" or "completed"` + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `completion_tokens: number` - - `"in_progress"` + Number of completion tokens used over the course of the run. - - `"incomplete"` + - `prompt_tokens: number` - - `"completed"` + Number of prompt tokens used over the course of the run. - - `thread_id: string` + - `total_tokens: number` - The [thread](/docs/api-reference/threads) ID that this message belongs to. + Total number of tokens used (prompt + completion). -- `first_id: string` + - `temperature: optional number` -- `has_more: boolean` + The sampling temperature used for this run. If not set, defaults to 1. -- `last_id: string` + - `top_p: optional number` -- `object: string` + The nucleus sampling value used for this run. If not set, defaults to 1. ### Example ```http -curl https://api.openai.com/v1/threads/$THREAD_ID/messages \ +curl https://api.openai.com/v1/threads/$THREAD_ID/runs/$RUN_ID \ + -H 'Content-Type: application/json' \ -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" + -H "Authorization: Bearer $OPENAI_API_KEY" \ + -d '{}' ``` #### Response ```json { - "data": [ - { "id": "id", "assistant_id": "assistant_id", - "attachments": [ - { - "file_id": "file_id", - "tools": [ - { - "type": "code_interpreter" - } - ] - } - ], + "cancelled_at": 0, "completed_at": 0, - "content": [ - { - "image_file": { - "file_id": "file_id", - "detail": "auto" - }, - "type": "image_file" - } - ], "created_at": 0, - "incomplete_at": 0, + "expires_at": 0, + "failed_at": 0, "incomplete_details": { - "reason": "content_filter" + "reason": "max_completion_tokens" + }, + "instructions": "instructions", + "last_error": { + "code": "server_error", + "message": "message" }, + "max_completion_tokens": 256, + "max_prompt_tokens": 256, "metadata": { "foo": "string" }, - "object": "thread.message", - "role": "user", - "run_id": "run_id", - "status": "in_progress", - "thread_id": "thread_id" + "model": "model", + "object": "thread.run", + "parallel_tool_calls": true, + "required_action": { + "submit_tool_outputs": { + "tool_calls": [ + { + "id": "id", + "function": { + "arguments": "arguments", + "name": "name" + }, + "type": "function" + } + ] + }, + "type": "submit_tool_outputs" + }, + "response_format": "auto", + "started_at": 0, + "status": "queued", + "thread_id": "thread_id", + "tool_choice": "none", + "tools": [ + { + "type": "code_interpreter" } ], - "first_id": "msg_abc123", - "has_more": false, - "last_id": "msg_abc123", - "object": "list" + "truncation_strategy": { + "type": "auto", + "last_messages": 1 + }, + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + }, + "temperature": 0, + "top_p": 0 } ``` ### Example ```http -curl https://api.openai.com/v1/threads/thread_abc123/messages \ - -H "Content-Type: application/json" \ +curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: assistants=v2" + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" \ + -d '{ + "metadata": { + "user_id": "user_abc123" + } + }' ``` #### Response ```json { - "object": "list", - "data": [ - { - "id": "msg_abc123", - "object": "thread.message", - "created_at": 1699016383, - "assistant_id": null, - "thread_id": "thread_abc123", - "run_id": null, - "role": "user", - "content": [ - { - "type": "text", - "text": { - "value": "How does AI work? Explain it in simple terms.", - "annotations": [] - } - } - ], - "attachments": [], - "metadata": {} - }, - { - "id": "msg_abc456", - "object": "thread.message", - "created_at": 1699016383, - "assistant_id": null, + "id": "run_abc123", + "object": "thread.run", + "created_at": 1699075072, + "assistant_id": "asst_abc123", "thread_id": "thread_abc123", - "run_id": null, - "role": "user", - "content": [ + "status": "completed", + "started_at": 1699075072, + "expires_at": null, + "cancelled_at": null, + "failed_at": null, + "completed_at": 1699075073, + "last_error": null, + "model": "gpt-4o", + "instructions": null, + "incomplete_details": null, + "tools": [ { - "type": "text", - "text": { - "value": "Hello, what is AI?", - "annotations": [] - } + "type": "code_interpreter" } ], - "attachments": [], - "metadata": {} + "tool_resources": { + "code_interpreter": { + "file_ids": [ + "file-abc123", + "file-abc456" + ] } - ], - "first_id": "msg_abc123", - "last_id": "msg_abc456", - "has_more": false + }, + "metadata": { + "user_id": "user_abc123" + }, + "usage": { + "prompt_tokens": 123, + "completion_tokens": 456, + "total_tokens": 579 + }, + "temperature": 1.0, + "top_p": 1.0, + "max_prompt_tokens": 1000, + "max_completion_tokens": 1000, + "truncation_strategy": { + "type": "auto", + "last_messages": null + }, + "response_format": "auto", + "tool_choice": "auto", + "parallel_tool_calls": true } ``` -## Create message - -**post** `/threads/{thread_id}/messages` +## Domain Types -Create a message. +### Required Action Function Tool Call -### Path Parameters +- `RequiredActionFunctionToolCall object { id, function, type }` -- `thread_id: string` + Tool call objects -### Body Parameters + - `id: string` -- `content: string or array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlockParam` + The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](/docs/api-reference/runs/submitToolOutputs) endpoint. - The text contents of the message. + - `function: object { arguments, name }` - - `TextContent = string` + The function definition. - The text contents of the message. + - `arguments: string` - - `ArrayOfContentParts = array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlockParam` + The arguments that the model expects you to pass to the function. - An array of content parts with a defined type, each can be of type `text` or images can be passed with `image_url` or `image_file`. Image types are only supported on [Vision-compatible models](/docs/models). + - `name: string` - - `ImageFileContentBlock object { image_file, type }` + The name of the function. - References an image [File](/docs/api-reference/files) in the content of a message. + - `type: "function"` - - `image_file: ImageFile` + The type of tool call the output is required for. For now, this is always `function`. - - `file_id: string` + - `"function"` - The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. +### Run - - `detail: optional "auto" or "low" or "high"` +- `Run object { id, assistant_id, cancelled_at, 24 more }` - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + Represents an execution run on a [thread](/docs/api-reference/threads). - - `"auto"` + - `id: string` - - `"low"` + The identifier, which can be referenced in API endpoints. - - `"high"` + - `assistant_id: string` - - `type: "image_file"` + The ID of the [assistant](/docs/api-reference/assistants) used for execution of this run. - Always `image_file`. + - `cancelled_at: number` - - `"image_file"` + The Unix timestamp (in seconds) for when the run was cancelled. - - `ImageURLContentBlock object { image_url, type }` + - `completed_at: number` - References an image URL in the content of a message. + The Unix timestamp (in seconds) for when the run was completed. - - `image_url: ImageURL` + - `created_at: number` - - `url: string` + The Unix timestamp (in seconds) for when the run was created. - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `expires_at: number` - - `detail: optional "auto" or "low" or "high"` + The Unix timestamp (in seconds) for when the run will expire. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `failed_at: number` - - `"auto"` + The Unix timestamp (in seconds) for when the run failed. - - `"low"` + - `incomplete_details: object { reason }` - - `"high"` + Details on why the run is incomplete. Will be `null` if the run is not incomplete. - - `type: "image_url"` + - `reason: optional "max_completion_tokens" or "max_prompt_tokens"` - The type of the content part. + The reason why the run is incomplete. This will point to which specific token limit was reached over the course of the run. - - `"image_url"` + - `"max_completion_tokens"` - - `TextContentBlockParam object { text, type }` + - `"max_prompt_tokens"` - The text content that is part of a message. + - `instructions: string` - - `text: string` + The instructions that the [assistant](/docs/api-reference/assistants) used for this run. - Text content to be sent to the model + - `last_error: object { code, message }` - - `type: "text"` + The last error associated with this run. Will be `null` if there are no errors. - Always `text`. + - `code: "server_error" or "rate_limit_exceeded" or "invalid_prompt"` - - `"text"` + One of `server_error`, `rate_limit_exceeded`, or `invalid_prompt`. -- `role: "user" or "assistant"` + - `"server_error"` - The role of the entity that is creating the message. Allowed values include: + - `"rate_limit_exceeded"` - - `user`: Indicates the message is sent by an actual user and should be used in most cases to represent user-generated messages. - - `assistant`: Indicates the message is generated by the assistant. Use this value to insert messages from the assistant into the conversation. + - `"invalid_prompt"` - - `"user"` + - `message: string` - - `"assistant"` + A human-readable description of the error. -- `attachments: optional array of object { file_id, tools }` + - `max_completion_tokens: number` - A list of files attached to the message, and the tools they should be added to. + The maximum number of completion tokens specified to have been used over the course of the run. - - `file_id: optional string` + - `max_prompt_tokens: number` - The ID of the file to attach to the message. + The maximum number of prompt tokens specified to have been used over the course of the run. - - `tools: optional array of CodeInterpreterTool or object { type }` + - `metadata: Metadata` - The tools to add this file to. + 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. - - `CodeInterpreterTool object { type }` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `type: "code_interpreter"` + - `model: string` - The type of tool being defined: `code_interpreter` + The model that the [assistant](/docs/api-reference/assistants) used for this run. - - `"code_interpreter"` + - `object: "thread.run"` - - `FileSearchTool object { type }` + The object type, which is always `thread.run`. - - `type: "file_search"` + - `"thread.run"` - The type of tool being defined: `file_search` + - `parallel_tool_calls: boolean` - - `"file_search"` + Whether to enable [parallel function calling](/docs/guides/function-calling#configuring-parallel-function-calling) during tool use. -- `metadata: optional Metadata` + - `required_action: object { submit_tool_outputs, 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. + Details on the action required to continue the run. Will be `null` if no action is required. - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `submit_tool_outputs: object { tool_calls }` -### Returns + Details on the tool outputs needed for this run to continue. -- `Message object { id, assistant_id, attachments, 11 more }` + - `tool_calls: array of RequiredActionFunctionToolCall` - Represents a message within a [thread](/docs/api-reference/threads). + A list of the relevant tool calls. - `id: string` - The identifier, which can be referenced in API endpoints. + The ID of the tool call. This ID must be referenced when you submit the tool outputs in using the [Submit tool outputs to run](/docs/api-reference/runs/submitToolOutputs) endpoint. - - `assistant_id: string` + - `function: object { arguments, name }` - If applicable, the ID of the [assistant](/docs/api-reference/assistants) that authored this message. + The function definition. - - `attachments: array of object { file_id, tools }` + - `arguments: string` - A list of files attached to the message, and the tools they were added to. + The arguments that the model expects you to pass to the function. - - `file_id: optional string` + - `name: string` - The ID of the file to attach to the message. + The name of the function. - - `tools: optional array of CodeInterpreterTool or object { type }` + - `type: "function"` - The tools to add this file to. + The type of tool call the output is required for. For now, this is always `function`. - - `CodeInterpreterTool object { type }` + - `"function"` - - `type: "code_interpreter"` + - `type: "submit_tool_outputs"` - The type of tool being defined: `code_interpreter` + For now, this is always `submit_tool_outputs`. - - `"code_interpreter"` + - `"submit_tool_outputs"` - - `FileSearchTool object { type }` + - `response_format: AssistantResponseFormatOption` - - `type: "file_search"` + Specifies the format that the model must output. Compatible with [GPT-4o](/docs/models#gpt-4o), [GPT-4 Turbo](/docs/models#gpt-4-turbo-and-gpt-4), and all GPT-3.5 Turbo models since `gpt-3.5-turbo-1106`. - The type of tool being defined: `file_search` + Setting to `{ "type": "json_schema", "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_search"` + Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. - - `completed_at: number` + **Important:** when using JSON mode, you **must** also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if `finish_reason="length"`, which indicates the generation exceeded `max_tokens` or the conversation exceeded the max context length. - The Unix timestamp (in seconds) for when the message was completed. + - `"auto"` - - `content: array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlock or RefusalContentBlock` + `auto` is the default value - The content of the message in array of text and/or images. + - `"auto"` - - `ImageFileContentBlock object { image_file, type }` + - `ResponseFormatText object { type }` - References an image [File](/docs/api-reference/files) in the content of a message. + Default response format. Used to generate text responses. - - `image_file: ImageFile` + - `type: "text"` - - `file_id: string` + The type of response format being defined. Always `text`. - The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + - `"text"` - - `detail: optional "auto" or "low" or "high"` + - `ResponseFormatJSONObject object { type }` - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + 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. - - `"auto"` + - `type: "json_object"` - - `"low"` + The type of response format being defined. Always `json_object`. - - `"high"` + - `"json_object"` - - `type: "image_file"` + - `ResponseFormatJSONSchema object { json_schema, type }` - Always `image_file`. + JSON Schema response format. Used to generate structured JSON responses. + Learn more about [Structured Outputs](/docs/guides/structured-outputs). - - `"image_file"` + - `json_schema: object { name, description, schema, strict }` - - `ImageURLContentBlock object { image_url, type }` + Structured Outputs configuration options, including a JSON Schema. - References an image URL in the content of a message. + - `name: string` - - `image_url: ImageURL` + 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. - - `url: string` + - `description: optional string` - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + A description of what the response format is for, used by the model to + determine how to respond in the format. - - `detail: optional "auto" or "low" or "high"` + - `schema: optional map[unknown]` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + The schema for the response format, described as a JSON Schema object. + Learn how to build JSON schemas [here](https://json-schema.org/). + + - `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). + + - `type: "json_schema"` + + The type of response format being defined. Always `json_schema`. + + - `"json_schema"` + + - `started_at: number` + + The Unix timestamp (in seconds) for when the run was started. + + - `status: "queued" or "in_progress" or "requires_action" or 6 more` + + The status of the run, which can be either `queued`, `in_progress`, `requires_action`, `cancelling`, `cancelled`, `failed`, `completed`, `incomplete`, or `expired`. + + - `"queued"` + + - `"in_progress"` + + - `"requires_action"` + + - `"cancelling"` + + - `"cancelled"` + + - `"failed"` + + - `"completed"` + + - `"incomplete"` + + - `"expired"` + + - `thread_id: string` + + The ID of the [thread](/docs/api-reference/threads) that was executed on as a part of this run. + + - `tool_choice: AssistantToolChoiceOption` + + Controls which (if any) tool is called by the model. + `none` means the model will not call any tools and instead generates a message. + `auto` is the default value and means the model can pick between generating a message or calling one or more tools. + `required` means the model must call one or more tools before responding to the user. + Specifying a particular tool like `{"type": "file_search"}` or `{"type": "function", "function": {"name": "my_function"}}` forces the model to call that tool. + + - `"none" or "auto" or "required"` + + `none` means the model will not call any tools and instead generates a message. `auto` means the model can pick between generating a message or calling one or more tools. `required` means the model must call one or more tools before responding to the user. + + - `"none"` - `"auto"` - - `"low"` + - `"required"` - - `"high"` + - `AssistantToolChoice object { type, function }` - - `type: "image_url"` + Specifies a tool the model should use. Use to force the model to call a specific tool. - The type of the content part. + - `type: "function" or "code_interpreter" or "file_search"` - - `"image_url"` + The type of the tool. If type is `function`, the function name must be set - - `TextContentBlock object { text, type }` + - `"function"` - The text content that is part of a message. + - `"code_interpreter"` - - `text: Text` + - `"file_search"` - - `annotations: array of FileCitationAnnotation or FilePathAnnotation` + - `function: optional AssistantToolChoiceFunction` - - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` + - `name: string` - A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + The name of the function to call. - - `end_index: number` + - `tools: array of CodeInterpreterTool or FileSearchTool or FunctionTool` - - `file_citation: object { file_id }` + The list of tools that the [assistant](/docs/api-reference/assistants) used for this run. - - `file_id: string` + - `CodeInterpreterTool object { type }` - The ID of the specific File the citation is from. + - `type: "code_interpreter"` - - `start_index: number` + The type of tool being defined: `code_interpreter` - - `text: string` + - `"code_interpreter"` - The text in the message content that needs to be replaced. + - `FileSearchTool object { type, file_search }` - - `type: "file_citation"` + - `type: "file_search"` - Always `file_citation`. + The type of tool being defined: `file_search` - - `"file_citation"` + - `"file_search"` - - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` + - `file_search: optional object { max_num_results, ranking_options }` - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + Overrides for the file search tool. - - `end_index: number` + - `max_num_results: optional number` - - `file_path: object { file_id }` + The maximum number of results the file search tool should output. The default is 20 for `gpt-4*` models and 5 for `gpt-3.5-turbo`. This number should be between 1 and 50 inclusive. - - `file_id: string` + Note that the file search tool may output fewer than `max_num_results` results. See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - The ID of the file that was generated. + - `ranking_options: optional object { score_threshold, ranker }` - - `start_index: number` + The ranking options for the file search. If not specified, the file search tool will use the `auto` ranker and a score_threshold of 0. - - `text: string` + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. - The text in the message content that needs to be replaced. + - `score_threshold: number` - - `type: "file_path"` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - Always `file_path`. + - `ranker: optional "auto" or "default_2024_08_21"` - - `"file_path"` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `value: string` + - `"auto"` - The data that makes up the text. + - `"default_2024_08_21"` - - `type: "text"` + - `FunctionTool object { function, type }` - Always `text`. + - `function: FunctionDefinition` - - `"text"` + - `name: string` - - `RefusalContentBlock object { refusal, type }` + The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64. - The refusal content generated by the assistant. + - `description: optional string` - - `refusal: string` + A description of what the function does, used by the model to choose when and how to call the function. - - `type: "refusal"` + - `parameters: optional FunctionParameters` - Always `refusal`. + The parameters the functions accepts, described as a JSON Schema object. See the [guide](/docs/guides/function-calling) for examples, and the [JSON Schema reference](https://json-schema.org/understanding-json-schema/) for documentation about the format. - - `"refusal"` + Omitting `parameters` defines a function with an empty parameter list. - - `created_at: number` + - `strict: optional boolean` - The Unix timestamp (in seconds) for when the message was created. + Whether to enable strict schema adherence when generating the function call. If set to true, the model will follow the exact schema defined in the `parameters` field. Only a subset of JSON Schema is supported when `strict` is `true`. Learn more about Structured Outputs in the [function calling guide](/docs/guides/function-calling). - - `incomplete_at: number` + - `type: "function"` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + The type of tool being defined: `function` - - `incomplete_details: object { reason }` + - `"function"` - On an incomplete message, details about why the message is incomplete. + - `truncation_strategy: object { type, last_messages }` - - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` + Controls for how a thread will be truncated prior to the run. Use this to control the initial context window of the run. - The reason the message is incomplete. + - `type: "auto" or "last_messages"` - - `"content_filter"` + The truncation strategy to use for the thread. The default is `auto`. If set to `last_messages`, the thread will be truncated to the n most recent messages in the thread. When set to `auto`, messages in the middle of the thread will be dropped to fit the context length of the model, `max_prompt_tokens`. - - `"max_tokens"` + - `"auto"` - - `"run_cancelled"` + - `"last_messages"` - - `"run_expired"` + - `last_messages: optional number` - - `"run_failed"` + The number of most recent messages from the thread when constructing the context for the run. - - `metadata: Metadata` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - 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. + Usage statistics related to the run. This value will be `null` if the run is not in a terminal state (i.e. `in_progress`, `queued`, etc.). - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + - `completion_tokens: number` - - `object: "thread.message"` + Number of completion tokens used over the course of the run. - The object type, which is always `thread.message`. + - `prompt_tokens: number` - - `"thread.message"` + Number of prompt tokens used over the course of the run. - - `role: "user" or "assistant"` + - `total_tokens: number` - The entity that produced the message. One of `user` or `assistant`. + Total number of tokens used (prompt + completion). - - `"user"` + - `temperature: optional number` - - `"assistant"` + The sampling temperature used for this run. If not set, defaults to 1. - - `run_id: string` + - `top_p: optional number` - The ID of the [run](/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + The nucleus sampling value used for this run. If not set, defaults to 1. - - `status: "in_progress" or "incomplete" or "completed"` +# Steps - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. +## List run steps - - `"in_progress"` +**get** `/threads/{thread_id}/runs/{run_id}/steps` - - `"incomplete"` +Returns a list of run steps belonging to a run. - - `"completed"` +### Path Parameters - - `thread_id: string` +- `thread_id: string` - The [thread](/docs/api-reference/threads) ID that this message belongs to. +- `run_id: string` -### Example +### Query Parameters -```http -curl https://api.openai.com/v1/threads/$THREAD_ID/messages \ - -H 'Content-Type: application/json' \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{ - "content": "string", - "role": "user" - }' -``` +- `after: optional string` -#### Response + A cursor for use in pagination. `after` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, ending with obj_foo, your subsequent call can include after=obj_foo in order to fetch the next page of the list. -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "attachments": [ - { - "file_id": "file_id", - "tools": [ - { - "type": "code_interpreter" - } - ] - } - ], - "completed_at": 0, - "content": [ - { - "image_file": { - "file_id": "file_id", - "detail": "auto" - }, - "type": "image_file" - } - ], - "created_at": 0, - "incomplete_at": 0, - "incomplete_details": { - "reason": "content_filter" - }, - "metadata": { - "foo": "string" - }, - "object": "thread.message", - "role": "user", - "run_id": "run_id", - "status": "in_progress", - "thread_id": "thread_id" -} -``` +- `before: optional string` -### Example + A cursor for use in pagination. `before` is an object ID that defines your place in the list. For instance, if you make a list request and receive 100 objects, starting with obj_foo, your subsequent call can include before=obj_foo in order to fetch the previous page of the list. -```http -curl https://api.openai.com/v1/threads/thread_abc123/messages \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: assistants=v2" \ - -d '{ - "role": "user", - "content": "How does AI work? Explain it in simple terms." - }' -``` +- `include: optional array of RunStepInclude` -#### Response + A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. -```json -{ - "id": "msg_abc123", - "object": "thread.message", - "created_at": 1713226573, - "assistant_id": null, - "thread_id": "thread_abc123", - "run_id": null, - "role": "user", - "content": [ - { - "type": "text", - "text": { - "value": "How does AI work? Explain it in simple terms.", - "annotations": [] - } - } - ], - "attachments": [], - "metadata": {} -} -``` + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `"step_details.tool_calls[*].file_search.results[*].content"` + +- `limit: optional number` + + A limit on the number of objects to be returned. Limit can range between 1 and 100, and the default is 20. + +- `order: optional "asc" or "desc"` + + Sort order by the `created_at` timestamp of the objects. `asc` for ascending order and `desc` for descending order. + + - `"asc"` + + - `"desc"` + +### Returns + +- `data: array of RunStep` + + - `id: string` + + The identifier of the run step, which can be referenced in API endpoints. + + - `assistant_id: string` + + The ID of the [assistant](/docs/api-reference/assistants) associated with the run step. + + - `cancelled_at: number` + + The Unix timestamp (in seconds) for when the run step was cancelled. + + - `completed_at: number` + + The Unix timestamp (in seconds) for when the run step completed. + + - `created_at: number` + + The Unix timestamp (in seconds) for when the run step was created. + + - `expired_at: number` + + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. + + - `failed_at: number` + + The Unix timestamp (in seconds) for when the run step failed. + + - `last_error: object { code, message }` -## Modify message + The last error associated with this run step. Will be `null` if there are no errors. -**post** `/threads/{thread_id}/messages/{message_id}` + - `code: "server_error" or "rate_limit_exceeded"` -Modifies a message. + One of `server_error` or `rate_limit_exceeded`. -### Path Parameters + - `"server_error"` -- `thread_id: string` + - `"rate_limit_exceeded"` -- `message_id: string` + - `message: string` -### Body Parameters + A human-readable description of the error. -- `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 @@ -232622,720 +232782,662 @@ Modifies a message. Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. -### Returns - -- `Message object { id, assistant_id, attachments, 11 more }` - - Represents a message within a [thread](/docs/api-reference/threads). - - - `id: string` + - `object: "thread.run.step"` - The identifier, which can be referenced in API endpoints. + The object type, which is always `thread.run.step`. - - `assistant_id: string` + - `"thread.run.step"` - If applicable, the ID of the [assistant](/docs/api-reference/assistants) that authored this message. + - `run_id: string` - - `attachments: array of object { file_id, tools }` + The ID of the [run](/docs/api-reference/runs) that this run step is a part of. - A list of files attached to the message, and the tools they were added to. + - `status: "in_progress" or "cancelled" or "failed" or 2 more` - - `file_id: optional string` + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - The ID of the file to attach to the message. + - `"in_progress"` - - `tools: optional array of CodeInterpreterTool or object { type }` + - `"cancelled"` - The tools to add this file to. + - `"failed"` - - `CodeInterpreterTool object { type }` + - `"completed"` - - `type: "code_interpreter"` + - `"expired"` - The type of tool being defined: `code_interpreter` + - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` - - `"code_interpreter"` + The details of the run step. - - `FileSearchTool object { type }` + - `MessageCreationStepDetails object { message_creation, type }` - - `type: "file_search"` + Details of the message creation by the run step. - The type of tool being defined: `file_search` + - `message_creation: object { message_id }` - - `"file_search"` + - `message_id: string` - - `completed_at: number` + The ID of the message that was created by this run step. - The Unix timestamp (in seconds) for when the message was completed. + - `type: "message_creation"` - - `content: array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlock or RefusalContentBlock` + Always `message_creation`. - The content of the message in array of text and/or images. + - `"message_creation"` - - `ImageFileContentBlock object { image_file, type }` + - `ToolCallsStepDetails object { tool_calls, type }` - References an image [File](/docs/api-reference/files) in the content of a message. + Details of the tool call. - - `image_file: ImageFile` + - `tool_calls: array of CodeInterpreterToolCall or FileSearchToolCall or FunctionToolCall` - - `file_id: string` + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + - `CodeInterpreterToolCall object { id, code_interpreter, type }` - - `detail: optional "auto" or "low" or "high"` + Details of the Code Interpreter tool call the run step was involved in. - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `id: string` - - `"auto"` + The ID of the tool call. - - `"low"` + - `code_interpreter: object { input, outputs }` - - `"high"` + The Code Interpreter tool call definition. - - `type: "image_file"` + - `input: string` - Always `image_file`. + The input to the Code Interpreter tool call. - - `"image_file"` + - `outputs: array of object { logs, type } or object { image, type }` - - `ImageURLContentBlock object { image_url, type }` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - References an image URL in the content of a message. + - `CodeInterpreterLogOutput object { logs, type }` - - `image_url: ImageURL` + Text output from the Code Interpreter tool call as part of a run step. - - `url: string` + - `logs: string` - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + The text output from the Code Interpreter tool call. - - `detail: optional "auto" or "low" or "high"` + - `type: "logs"` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + Always `logs`. - - `"auto"` + - `"logs"` - - `"low"` + - `CodeInterpreterImageOutput object { image, type }` - - `"high"` + - `image: object { file_id }` - - `type: "image_url"` + - `file_id: string` - The type of the content part. + The [file](/docs/api-reference/files) ID of the image. - - `"image_url"` + - `type: "image"` - - `TextContentBlock object { text, type }` + Always `image`. - The text content that is part of a message. + - `"image"` - - `text: Text` + - `type: "code_interpreter"` - - `annotations: array of FileCitationAnnotation or FilePathAnnotation` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` + - `"code_interpreter"` - A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + - `FileSearchToolCall object { id, file_search, type }` - - `end_index: number` + - `id: string` - - `file_citation: object { file_id }` + The ID of the tool call object. - - `file_id: string` + - `file_search: object { ranking_options, results }` - The ID of the specific File the citation is from. + For now, this is always going to be an empty object. - - `start_index: number` + - `ranking_options: optional object { ranker, score_threshold }` - - `text: string` + The ranking options for the file search. - The text in the message content that needs to be replaced. + - `ranker: "auto" or "default_2024_08_21"` - - `type: "file_citation"` + The ranker to use for the file search. If not specified will use the `auto` ranker. - Always `file_citation`. + - `"auto"` - - `"file_citation"` + - `"default_2024_08_21"` - - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` + - `score_threshold: number` - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `end_index: number` + - `results: optional array of object { file_id, file_name, score, content }` - - `file_path: object { file_id }` + The results of the file search. - `file_id: string` - The ID of the file that was generated. + The ID of the file that result was found in. - - `start_index: number` + - `file_name: string` - - `text: string` + The name of the file that result was found in. - The text in the message content that needs to be replaced. + - `score: number` - - `type: "file_path"` + The score of the result. All values must be a floating point number between 0 and 1. - Always `file_path`. + - `content: optional array of object { text, type }` - - `"file_path"` + The content of the result that was found. The content is only included if requested via the include query parameter. - - `value: string` + - `text: optional string` - The data that makes up the text. + The text content of the file. - - `type: "text"` + - `type: optional "text"` - Always `text`. + The type of the content. - `"text"` - - `RefusalContentBlock object { refusal, type }` + - `type: "file_search"` - The refusal content generated by the assistant. + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `refusal: string` + - `"file_search"` - - `type: "refusal"` + - `FunctionToolCall object { id, function, type }` - Always `refusal`. + - `id: string` - - `"refusal"` + The ID of the tool call object. - - `created_at: number` + - `function: object { arguments, name, output }` - The Unix timestamp (in seconds) for when the message was created. + The definition of the function that was called. - - `incomplete_at: number` + - `arguments: string` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + The arguments passed to the function. - - `incomplete_details: object { reason }` + - `name: string` - On an incomplete message, details about why the message is incomplete. + The name of the function. - - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` + - `output: string` - The reason the message is incomplete. + The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. - - `"content_filter"` + - `type: "function"` - - `"max_tokens"` + The type of tool call. This is always going to be `function` for this type of tool call. - - `"run_cancelled"` + - `"function"` - - `"run_expired"` + - `type: "tool_calls"` - - `"run_failed"` + Always `tool_calls`. - - `metadata: Metadata` + - `"tool_calls"` - 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. + - `thread_id: string` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The ID of the [thread](/docs/api-reference/threads) that was run. - - `object: "thread.message"` + - `type: "message_creation" or "tool_calls"` - The object type, which is always `thread.message`. + The type of run step, which can be either `message_creation` or `tool_calls`. - - `"thread.message"` + - `"message_creation"` - - `role: "user" or "assistant"` + - `"tool_calls"` - The entity that produced the message. One of `user` or `assistant`. + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - - `"user"` + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - - `"assistant"` + - `completion_tokens: number` - - `run_id: string` + Number of completion tokens used over the course of the run step. - The ID of the [run](/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + - `prompt_tokens: number` - - `status: "in_progress" or "incomplete" or "completed"` + Number of prompt tokens used over the course of the run step. - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + - `total_tokens: number` - - `"in_progress"` + Total number of tokens used (prompt + completion). - - `"incomplete"` +- `first_id: string` - - `"completed"` +- `has_more: boolean` - - `thread_id: string` +- `last_id: string` - The [thread](/docs/api-reference/threads) ID that this message belongs to. +- `object: string` ### Example ```http -curl https://api.openai.com/v1/threads/$THREAD_ID/messages/$MESSAGE_ID \ - -H 'Content-Type: application/json' \ +curl https://api.openai.com/v1/threads/$THREAD_ID/runs/$RUN_ID/steps \ -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -d '{}' + -H "Authorization: Bearer $OPENAI_API_KEY" ``` #### Response ```json { + "data": [ + { "id": "id", "assistant_id": "assistant_id", - "attachments": [ - { - "file_id": "file_id", - "tools": [ - { - "type": "code_interpreter" - } - ] - } - ], + "cancelled_at": 0, "completed_at": 0, - "content": [ - { - "image_file": { - "file_id": "file_id", - "detail": "auto" - }, - "type": "image_file" - } - ], "created_at": 0, - "incomplete_at": 0, - "incomplete_details": { - "reason": "content_filter" + "expired_at": 0, + "failed_at": 0, + "last_error": { + "code": "server_error", + "message": "message" }, "metadata": { "foo": "string" }, - "object": "thread.message", - "role": "user", + "object": "thread.run.step", "run_id": "run_id", "status": "in_progress", - "thread_id": "thread_id" + "step_details": { + "message_creation": { + "message_id": "message_id" + }, + "type": "message_creation" + }, + "thread_id": "thread_id", + "type": "message_creation", + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + } + } + ], + "first_id": "step_abc123", + "has_more": false, + "last_id": "step_abc456", + "object": "list" } ``` ### Example ```http -curl https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 \ - -H "Content-Type: application/json" \ +curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/steps \ -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: assistants=v2" \ - -d '{ - "metadata": { - "modified": "true", - "user": "abc123" - } - }' + -H "Content-Type: application/json" \ + -H "OpenAI-Beta: assistants=v2" ``` #### Response ```json { - "id": "msg_abc123", - "object": "thread.message", - "created_at": 1699017614, - "assistant_id": null, - "thread_id": "thread_abc123", - "run_id": null, - "role": "user", - "content": [ + "object": "list", + "data": [ { - "type": "text", - "text": { - "value": "How does AI work? Explain it in simple terms.", - "annotations": [] + "id": "step_abc123", + "object": "thread.run.step", + "created_at": 1699063291, + "run_id": "run_abc123", + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "type": "message_creation", + "status": "completed", + "cancelled_at": null, + "completed_at": 1699063291, + "expired_at": null, + "failed_at": null, + "last_error": null, + "step_details": { + "type": "message_creation", + "message_creation": { + "message_id": "msg_abc123" } + }, + "usage": { + "prompt_tokens": 123, + "completion_tokens": 456, + "total_tokens": 579 } - ], - "file_ids": [], - "metadata": { - "modified": "true", - "user": "abc123" } + ], + "first_id": "step_abc123", + "last_id": "step_abc456", + "has_more": false } ``` -## Retrieve message +## Retrieve run step -**get** `/threads/{thread_id}/messages/{message_id}` +**get** `/threads/{thread_id}/runs/{run_id}/steps/{step_id}` -Retrieve a message. +Retrieves a run step. ### Path Parameters - `thread_id: string` -- `message_id: string` +- `run_id: string` + +- `step_id: string` + +### Query Parameters + +- `include: optional array of RunStepInclude` + + A list of additional fields to include in the response. Currently the only supported value is `step_details.tool_calls[*].file_search.results[*].content` to fetch the file search result content. + + See the [file search tool documentation](/docs/assistants/tools/file-search#customizing-file-search-settings) for more information. + + - `"step_details.tool_calls[*].file_search.results[*].content"` ### Returns -- `Message object { id, assistant_id, attachments, 11 more }` +- `RunStep object { id, assistant_id, cancelled_at, 13 more }` - Represents a message within a [thread](/docs/api-reference/threads). + Represents a step in execution of a run. - `id: string` - The identifier, which can be referenced in API endpoints. + The identifier of the run step, which can be referenced in API endpoints. - `assistant_id: string` - If applicable, the ID of the [assistant](/docs/api-reference/assistants) that authored this message. + The ID of the [assistant](/docs/api-reference/assistants) associated with the run step. - - `attachments: array of object { file_id, tools }` + - `cancelled_at: number` - A list of files attached to the message, and the tools they were added to. + The Unix timestamp (in seconds) for when the run step was cancelled. - - `file_id: optional string` + - `completed_at: number` - The ID of the file to attach to the message. + The Unix timestamp (in seconds) for when the run step completed. - - `tools: optional array of CodeInterpreterTool or object { type }` + - `created_at: number` - The tools to add this file to. + The Unix timestamp (in seconds) for when the run step was created. - - `CodeInterpreterTool object { type }` + - `expired_at: number` - - `type: "code_interpreter"` + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - The type of tool being defined: `code_interpreter` + - `failed_at: number` - - `"code_interpreter"` + The Unix timestamp (in seconds) for when the run step failed. - - `FileSearchTool object { type }` + - `last_error: object { code, message }` - - `type: "file_search"` + The last error associated with this run step. Will be `null` if there are no errors. - The type of tool being defined: `file_search` + - `code: "server_error" or "rate_limit_exceeded"` - - `"file_search"` + One of `server_error` or `rate_limit_exceeded`. - - `completed_at: number` + - `"server_error"` - The Unix timestamp (in seconds) for when the message was completed. + - `"rate_limit_exceeded"` - - `content: array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlock or RefusalContentBlock` + - `message: string` - The content of the message in array of text and/or images. + A human-readable description of the error. - - `ImageFileContentBlock object { image_file, type }` + - `metadata: Metadata` - References an image [File](/docs/api-reference/files) in the content of a message. + 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. - - `image_file: ImageFile` + Keys are strings with a maximum length of 64 characters. Values are strings + with a maximum length of 512 characters. - - `file_id: string` + - `object: "thread.run.step"` - The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + The object type, which is always `thread.run.step`. - - `detail: optional "auto" or "low" or "high"` + - `"thread.run.step"` - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `run_id: string` - - `"auto"` + The ID of the [run](/docs/api-reference/runs) that this run step is a part of. - - `"low"` + - `status: "in_progress" or "cancelled" or "failed" or 2 more` - - `"high"` + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - - `type: "image_file"` + - `"in_progress"` - Always `image_file`. + - `"cancelled"` - - `"image_file"` + - `"failed"` - - `ImageURLContentBlock object { image_url, type }` + - `"completed"` - References an image URL in the content of a message. + - `"expired"` - - `image_url: ImageURL` + - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` - - `url: string` + The details of the run step. - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `MessageCreationStepDetails object { message_creation, type }` - - `detail: optional "auto" or "low" or "high"` + Details of the message creation by the run step. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `message_creation: object { message_id }` - - `"auto"` + - `message_id: string` - - `"low"` + The ID of the message that was created by this run step. - - `"high"` + - `type: "message_creation"` - - `type: "image_url"` + Always `message_creation`. - The type of the content part. + - `"message_creation"` - - `"image_url"` + - `ToolCallsStepDetails object { tool_calls, type }` - - `TextContentBlock object { text, type }` + Details of the tool call. - The text content that is part of a message. + - `tool_calls: array of CodeInterpreterToolCall or FileSearchToolCall or FunctionToolCall` - - `text: Text` + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - - `annotations: array of FileCitationAnnotation or FilePathAnnotation` + - `CodeInterpreterToolCall object { id, code_interpreter, type }` - - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` + Details of the Code Interpreter tool call the run step was involved in. - A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + - `id: string` - - `end_index: number` + The ID of the tool call. - - `file_citation: object { file_id }` + - `code_interpreter: object { input, outputs }` - - `file_id: string` + The Code Interpreter tool call definition. - The ID of the specific File the citation is from. + - `input: string` - - `start_index: number` + The input to the Code Interpreter tool call. - - `text: string` + - `outputs: array of object { logs, type } or object { image, type }` - The text in the message content that needs to be replaced. + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `type: "file_citation"` + - `CodeInterpreterLogOutput object { logs, type }` - Always `file_citation`. + Text output from the Code Interpreter tool call as part of a run step. - - `"file_citation"` + - `logs: string` - - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` + The text output from the Code Interpreter tool call. - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `type: "logs"` - - `end_index: number` + Always `logs`. - - `file_path: object { file_id }` + - `"logs"` - - `file_id: string` + - `CodeInterpreterImageOutput object { image, type }` - The ID of the file that was generated. + - `image: object { file_id }` - - `start_index: number` + - `file_id: string` - - `text: string` + The [file](/docs/api-reference/files) ID of the image. - The text in the message content that needs to be replaced. + - `type: "image"` - - `type: "file_path"` + Always `image`. - Always `file_path`. + - `"image"` - - `"file_path"` + - `type: "code_interpreter"` - - `value: string` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - The data that makes up the text. + - `"code_interpreter"` - - `type: "text"` + - `FileSearchToolCall object { id, file_search, type }` - Always `text`. + - `id: string` - - `"text"` + The ID of the tool call object. - - `RefusalContentBlock object { refusal, type }` + - `file_search: object { ranking_options, results }` - The refusal content generated by the assistant. + For now, this is always going to be an empty object. - - `refusal: string` + - `ranking_options: optional object { ranker, score_threshold }` - - `type: "refusal"` + The ranking options for the file search. - Always `refusal`. + - `ranker: "auto" or "default_2024_08_21"` - - `"refusal"` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `created_at: number` + - `"auto"` - The Unix timestamp (in seconds) for when the message was created. + - `"default_2024_08_21"` - - `incomplete_at: number` + - `score_threshold: number` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `incomplete_details: object { reason }` + - `results: optional array of object { file_id, file_name, score, content }` - On an incomplete message, details about why the message is incomplete. + The results of the file search. - - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` + - `file_id: string` - The reason the message is incomplete. + The ID of the file that result was found in. - - `"content_filter"` + - `file_name: string` - - `"max_tokens"` + The name of the file that result was found in. - - `"run_cancelled"` + - `score: number` - - `"run_expired"` + The score of the result. All values must be a floating point number between 0 and 1. - - `"run_failed"` + - `content: optional array of object { text, type }` - - `metadata: Metadata` + The content of the result that was found. The content is only included if requested via the include query parameter. - 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. + - `text: optional string` - Keys are strings with a maximum length of 64 characters. Values are strings - with a maximum length of 512 characters. + The text content of the file. - - `object: "thread.message"` + - `type: optional "text"` - The object type, which is always `thread.message`. + The type of the content. - - `"thread.message"` + - `"text"` - - `role: "user" or "assistant"` + - `type: "file_search"` - The entity that produced the message. One of `user` or `assistant`. + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `"user"` + - `"file_search"` - - `"assistant"` + - `FunctionToolCall object { id, function, type }` - - `run_id: string` + - `id: string` - The ID of the [run](/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + The ID of the tool call object. - - `status: "in_progress" or "incomplete" or "completed"` + - `function: object { arguments, name, output }` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + The definition of the function that was called. - - `"in_progress"` + - `arguments: string` - - `"incomplete"` + The arguments passed to the function. - - `"completed"` + - `name: string` - - `thread_id: string` + The name of the function. - The [thread](/docs/api-reference/threads) ID that this message belongs to. + - `output: string` -### Example + The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. -```http -curl https://api.openai.com/v1/threads/$THREAD_ID/messages/$MESSAGE_ID \ - -H 'OpenAI-Beta: assistants=v2' \ - -H "Authorization: Bearer $OPENAI_API_KEY" -``` + - `type: "function"` -#### Response + The type of tool call. This is always going to be `function` for this type of tool call. -```json -{ - "id": "id", - "assistant_id": "assistant_id", - "attachments": [ - { - "file_id": "file_id", - "tools": [ - { - "type": "code_interpreter" - } - ] - } - ], - "completed_at": 0, - "content": [ - { - "image_file": { - "file_id": "file_id", - "detail": "auto" - }, - "type": "image_file" - } - ], - "created_at": 0, - "incomplete_at": 0, - "incomplete_details": { - "reason": "content_filter" - }, - "metadata": { - "foo": "string" - }, - "object": "thread.message", - "role": "user", - "run_id": "run_id", - "status": "in_progress", - "thread_id": "thread_id" -} -``` + - `"function"` -### Example + - `type: "tool_calls"` -```http -curl https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 \ - -H "Content-Type: application/json" \ - -H "Authorization: Bearer $OPENAI_API_KEY" \ - -H "OpenAI-Beta: assistants=v2" -``` + Always `tool_calls`. -#### Response + - `"tool_calls"` -```json -{ - "id": "msg_abc123", - "object": "thread.message", - "created_at": 1699017614, - "assistant_id": null, - "thread_id": "thread_abc123", - "run_id": null, - "role": "user", - "content": [ - { - "type": "text", - "text": { - "value": "How does AI work? Explain it in simple terms.", - "annotations": [] - } - } - ], - "attachments": [], - "metadata": {} -} -``` + - `thread_id: string` -## Delete message + The ID of the [thread](/docs/api-reference/threads) that was run. -**delete** `/threads/{thread_id}/messages/{message_id}` + - `type: "message_creation" or "tool_calls"` -Deletes a message. + The type of run step, which can be either `message_creation` or `tool_calls`. -### Path Parameters + - `"message_creation"` -- `thread_id: string` + - `"tool_calls"` -- `message_id: string` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` -### Returns + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. -- `MessageDeleted object { id, deleted, object }` + - `completion_tokens: number` - - `id: string` + Number of completion tokens used over the course of the run step. - - `deleted: boolean` + - `prompt_tokens: number` - - `object: "thread.message.deleted"` + Number of prompt tokens used over the course of the run step. - - `"thread.message.deleted"` + - `total_tokens: number` + + Total number of tokens used (prompt + completion). ### Example ```http -curl https://api.openai.com/v1/threads/$THREAD_ID/messages/$MESSAGE_ID \ - -X DELETE \ +curl https://api.openai.com/v1/threads/$THREAD_ID/runs/$RUN_ID/steps/$STEP_ID \ -H 'OpenAI-Beta: assistants=v2' \ -H "Authorization: Bearer $OPENAI_API_KEY" ``` @@ -233345,17 +233447,44 @@ curl https://api.openai.com/v1/threads/$THREAD_ID/messages/$MESSAGE_ID \ ```json { "id": "id", - "deleted": true, - "object": "thread.message.deleted" + "assistant_id": "assistant_id", + "cancelled_at": 0, + "completed_at": 0, + "created_at": 0, + "expired_at": 0, + "failed_at": 0, + "last_error": { + "code": "server_error", + "message": "message" + }, + "metadata": { + "foo": "string" + }, + "object": "thread.run.step", + "run_id": "run_id", + "status": "in_progress", + "step_details": { + "message_creation": { + "message_id": "message_id" + }, + "type": "message_creation" + }, + "thread_id": "thread_id", + "type": "message_creation", + "usage": { + "completion_tokens": 0, + "prompt_tokens": 0, + "total_tokens": 0 + } } ``` ### Example ```http -curl -X DELETE https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc123 \ - -H "Content-Type: application/json" \ +curl https://api.openai.com/v1/threads/thread_abc123/runs/run_abc123/steps/step_abc123 \ -H "Authorization: Bearer $OPENAI_API_KEY" \ + -H "Content-Type: application/json" \ -H "OpenAI-Beta: assistants=v2" ``` @@ -233363,527 +233492,416 @@ curl -X DELETE https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc1 ```json { - "id": "msg_abc123", - "object": "thread.message.deleted", - "deleted": true + "id": "step_abc123", + "object": "thread.run.step", + "created_at": 1699063291, + "run_id": "run_abc123", + "assistant_id": "asst_abc123", + "thread_id": "thread_abc123", + "type": "message_creation", + "status": "completed", + "cancelled_at": null, + "completed_at": 1699063291, + "expired_at": null, + "failed_at": null, + "last_error": null, + "step_details": { + "type": "message_creation", + "message_creation": { + "message_id": "msg_abc123" + } + }, + "usage": { + "prompt_tokens": 123, + "completion_tokens": 456, + "total_tokens": 579 + } } ``` ## Domain Types -### File Citation Annotation - -- `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` - - A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. - - - `end_index: number` - - - `file_citation: object { file_id }` - - - `file_id: string` - - The ID of the specific File the citation is from. - - - `start_index: number` - - - `text: string` - - The text in the message content that needs to be replaced. - - - `type: "file_citation"` - - Always `file_citation`. - - - `"file_citation"` - -### File Citation Delta Annotation +### Code Interpreter Logs -- `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` +- `CodeInterpreterLogs object { index, type, logs }` - A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + Text output from the Code Interpreter tool call as part of a run step. - `index: number` - The index of the annotation in the text content part. - - - `type: "file_citation"` - - Always `file_citation`. - - - `"file_citation"` - - - `end_index: optional number` - - - `file_citation: optional object { file_id, quote }` - - - `file_id: optional string` - - The ID of the specific File the citation is from. - - - `quote: optional string` - - The specific quote in the file. - - - `start_index: optional number` - - - `text: optional string` - - The text in the message content that needs to be replaced. - -### File Path Annotation - -- `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` - - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. - - - `end_index: number` - - - `file_path: object { file_id }` - - - `file_id: string` - - The ID of the file that was generated. - - - `start_index: number` - - - `text: string` + The index of the output in the outputs array. - The text in the message content that needs to be replaced. + - `type: "logs"` - - `type: "file_path"` + Always `logs`. - Always `file_path`. + - `"logs"` - - `"file_path"` + - `logs: optional string` -### File Path Delta Annotation + The text output from the Code Interpreter tool call. -- `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` +### Code Interpreter Output Image - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. +- `CodeInterpreterOutputImage object { index, type, image }` - `index: number` - The index of the annotation in the text content part. - - - `type: "file_path"` + The index of the output in the outputs array. - Always `file_path`. + - `type: "image"` - - `"file_path"` + Always `image`. - - `end_index: optional number` + - `"image"` - - `file_path: optional object { file_id }` + - `image: optional object { file_id }` - `file_id: optional string` - The ID of the file that was generated. - - - `start_index: optional number` - - - `text: optional string` - - The text in the message content that needs to be replaced. - -### Image File - -- `ImageFile object { file_id, detail }` - - - `file_id: string` - - The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - - `detail: optional "auto" or "low" or "high"` - - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - - `"auto"` - - - `"low"` - - - `"high"` - -### Image File Content Block - -- `ImageFileContentBlock object { image_file, type }` - - References an image [File](/docs/api-reference/files) in the content of a message. - - - `image_file: ImageFile` - - - `file_id: string` - - The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. - - - `detail: optional "auto" or "low" or "high"` - - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - - `"auto"` - - - `"low"` - - - `"high"` - - - `type: "image_file"` - - Always `image_file`. - - - `"image_file"` - -### Image File Delta - -- `ImageFileDelta object { detail, file_id }` - - - `detail: optional "auto" or "low" or "high"` - - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. - - - `"auto"` - - - `"low"` + The [file](/docs/api-reference/files) ID of the image. - - `"high"` +### Code Interpreter Tool Call - - `file_id: optional string` +- `CodeInterpreterToolCall object { id, code_interpreter, type }` - The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + Details of the Code Interpreter tool call the run step was involved in. -### Image File Delta Block + - `id: string` -- `ImageFileDeltaBlock object { index, type, image_file }` + The ID of the tool call. - References an image [File](/docs/api-reference/files) in the content of a message. + - `code_interpreter: object { input, outputs }` - - `index: number` + The Code Interpreter tool call definition. - The index of the content part in the message. + - `input: string` - - `type: "image_file"` + The input to the Code Interpreter tool call. - Always `image_file`. + - `outputs: array of object { logs, type } or object { image, type }` - - `"image_file"` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `image_file: optional ImageFileDelta` + - `CodeInterpreterLogOutput object { logs, type }` - - `detail: optional "auto" or "low" or "high"` + Text output from the Code Interpreter tool call as part of a run step. - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `logs: string` - - `"auto"` + The text output from the Code Interpreter tool call. - - `"low"` + - `type: "logs"` - - `"high"` + Always `logs`. - - `file_id: optional string` + - `"logs"` - The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + - `CodeInterpreterImageOutput object { image, type }` -### Image URL + - `image: object { file_id }` -- `ImageURL object { url, detail }` + - `file_id: string` - - `url: string` + The [file](/docs/api-reference/files) ID of the image. - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `type: "image"` - - `detail: optional "auto" or "low" or "high"` + Always `image`. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `"image"` - - `"auto"` + - `type: "code_interpreter"` - - `"low"` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `"high"` + - `"code_interpreter"` -### Image URL Content Block +### Code Interpreter Tool Call Delta -- `ImageURLContentBlock object { image_url, type }` +- `CodeInterpreterToolCallDelta object { index, type, id, code_interpreter }` - References an image URL in the content of a message. + Details of the Code Interpreter tool call the run step was involved in. - - `image_url: ImageURL` + - `index: number` - - `url: string` + The index of the tool call in the tool calls array. - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `type: "code_interpreter"` - - `detail: optional "auto" or "low" or "high"` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `"code_interpreter"` - - `"auto"` + - `id: optional string` - - `"low"` + The ID of the tool call. - - `"high"` + - `code_interpreter: optional object { input, outputs }` - - `type: "image_url"` + The Code Interpreter tool call definition. - The type of the content part. + - `input: optional string` - - `"image_url"` + The input to the Code Interpreter tool call. -### Image URL Delta + - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` -- `ImageURLDelta object { detail, url }` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `detail: optional "auto" or "low" or "high"` + - `CodeInterpreterLogs object { index, type, logs }` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. + Text output from the Code Interpreter tool call as part of a run step. - - `"auto"` + - `index: number` - - `"low"` + The index of the output in the outputs array. - - `"high"` + - `type: "logs"` - - `url: optional string` + Always `logs`. - The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `"logs"` -### Image URL Delta Block + - `logs: optional string` -- `ImageURLDeltaBlock object { index, type, image_url }` + The text output from the Code Interpreter tool call. - References an image URL in the content of a message. + - `CodeInterpreterOutputImage object { index, type, image }` - `index: number` - The index of the content part in the message. + The index of the output in the outputs array. - - `type: "image_url"` + - `type: "image"` - Always `image_url`. + Always `image`. - - `"image_url"` + - `"image"` - - `image_url: optional ImageURLDelta` + - `image: optional object { file_id }` - - `detail: optional "auto" or "low" or "high"` + - `file_id: optional string` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. + The [file](/docs/api-reference/files) ID of the image. - - `"auto"` +### File Search Tool Call - - `"low"` +- `FileSearchToolCall object { id, file_search, type }` - - `"high"` + - `id: string` - - `url: optional string` + The ID of the tool call object. - The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `file_search: object { ranking_options, results }` -### Message + For now, this is always going to be an empty object. -- `Message object { id, assistant_id, attachments, 11 more }` + - `ranking_options: optional object { ranker, score_threshold }` - Represents a message within a [thread](/docs/api-reference/threads). + The ranking options for the file search. - - `id: string` + - `ranker: "auto" or "default_2024_08_21"` - The identifier, which can be referenced in API endpoints. + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `assistant_id: string` + - `"auto"` - If applicable, the ID of the [assistant](/docs/api-reference/assistants) that authored this message. + - `"default_2024_08_21"` - - `attachments: array of object { file_id, tools }` + - `score_threshold: number` - A list of files attached to the message, and the tools they were added to. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `file_id: optional string` + - `results: optional array of object { file_id, file_name, score, content }` - The ID of the file to attach to the message. + The results of the file search. - - `tools: optional array of CodeInterpreterTool or object { type }` + - `file_id: string` - The tools to add this file to. + The ID of the file that result was found in. - - `CodeInterpreterTool object { type }` + - `file_name: string` - - `type: "code_interpreter"` + The name of the file that result was found in. - The type of tool being defined: `code_interpreter` + - `score: number` - - `"code_interpreter"` + The score of the result. All values must be a floating point number between 0 and 1. - - `FileSearchTool object { type }` + - `content: optional array of object { text, type }` - - `type: "file_search"` + The content of the result that was found. The content is only included if requested via the include query parameter. - The type of tool being defined: `file_search` + - `text: optional string` - - `"file_search"` + The text content of the file. - - `completed_at: number` + - `type: optional "text"` - The Unix timestamp (in seconds) for when the message was completed. + The type of the content. - - `content: array of ImageFileContentBlock or ImageURLContentBlock or TextContentBlock or RefusalContentBlock` + - `"text"` - The content of the message in array of text and/or images. + - `type: "file_search"` - - `ImageFileContentBlock object { image_file, type }` + The type of tool call. This is always going to be `file_search` for this type of tool call. - References an image [File](/docs/api-reference/files) in the content of a message. + - `"file_search"` - - `image_file: ImageFile` +### File Search Tool Call Delta - - `file_id: string` +- `FileSearchToolCallDelta object { file_search, index, type, id }` - The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + - `file_search: unknown` - - `detail: optional "auto" or "low" or "high"` + For now, this is always going to be an empty object. - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `index: number` - - `"auto"` + The index of the tool call in the tool calls array. - - `"low"` + - `type: "file_search"` - - `"high"` + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `type: "image_file"` + - `"file_search"` - Always `image_file`. + - `id: optional string` - - `"image_file"` + The ID of the tool call object. - - `ImageURLContentBlock object { image_url, type }` +### Function Tool Call - References an image URL in the content of a message. +- `FunctionToolCall object { id, function, type }` - - `image_url: ImageURL` + - `id: string` - - `url: string` + The ID of the tool call object. - The external URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `function: object { arguments, name, output }` - - `detail: optional "auto" or "low" or "high"` + The definition of the function that was called. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. Default value is `auto` + - `arguments: string` - - `"auto"` + The arguments passed to the function. - - `"low"` + - `name: string` - - `"high"` + The name of the function. - - `type: "image_url"` + - `output: string` - The type of the content part. + The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. - - `"image_url"` + - `type: "function"` - - `TextContentBlock object { text, type }` + The type of tool call. This is always going to be `function` for this type of tool call. - The text content that is part of a message. + - `"function"` - - `text: Text` +### Function Tool Call Delta - - `annotations: array of FileCitationAnnotation or FilePathAnnotation` +- `FunctionToolCallDelta object { index, type, id, function }` - - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` + - `index: number` - A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + The index of the tool call in the tool calls array. - - `end_index: number` + - `type: "function"` - - `file_citation: object { file_id }` + The type of tool call. This is always going to be `function` for this type of tool call. - - `file_id: string` + - `"function"` - The ID of the specific File the citation is from. + - `id: optional string` - - `start_index: number` + The ID of the tool call object. - - `text: string` + - `function: optional object { arguments, name, output }` - The text in the message content that needs to be replaced. + The definition of the function that was called. - - `type: "file_citation"` + - `arguments: optional string` - Always `file_citation`. + The arguments passed to the function. - - `"file_citation"` + - `name: optional string` - - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` + The name of the function. - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `output: optional string` - - `end_index: number` + The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. - - `file_path: object { file_id }` +### Message Creation Step Details - - `file_id: string` +- `MessageCreationStepDetails object { message_creation, type }` - The ID of the file that was generated. + Details of the message creation by the run step. - - `start_index: number` + - `message_creation: object { message_id }` - - `text: string` + - `message_id: string` - The text in the message content that needs to be replaced. + The ID of the message that was created by this run step. - - `type: "file_path"` + - `type: "message_creation"` - Always `file_path`. + Always `message_creation`. - - `"file_path"` + - `"message_creation"` - - `value: string` +### Run Step - The data that makes up the text. +- `RunStep object { id, assistant_id, cancelled_at, 13 more }` - - `type: "text"` + Represents a step in execution of a run. - Always `text`. + - `id: string` - - `"text"` + The identifier of the run step, which can be referenced in API endpoints. - - `RefusalContentBlock object { refusal, type }` + - `assistant_id: string` - The refusal content generated by the assistant. + The ID of the [assistant](/docs/api-reference/assistants) associated with the run step. - - `refusal: string` + - `cancelled_at: number` - - `type: "refusal"` + The Unix timestamp (in seconds) for when the run step was cancelled. - Always `refusal`. + - `completed_at: number` - - `"refusal"` + The Unix timestamp (in seconds) for when the run step completed. - `created_at: number` - The Unix timestamp (in seconds) for when the message was created. + The Unix timestamp (in seconds) for when the run step was created. - - `incomplete_at: number` + - `expired_at: number` - The Unix timestamp (in seconds) for when the message was marked as incomplete. + The Unix timestamp (in seconds) for when the run step expired. A step is considered expired if the parent run is expired. - - `incomplete_details: object { reason }` + - `failed_at: number` - On an incomplete message, details about why the message is incomplete. + The Unix timestamp (in seconds) for when the run step failed. - - `reason: "content_filter" or "max_tokens" or "run_cancelled" or 2 more` + - `last_error: object { code, message }` - The reason the message is incomplete. + The last error associated with this run step. Will be `null` if there are no errors. - - `"content_filter"` + - `code: "server_error" or "rate_limit_exceeded"` - - `"max_tokens"` + One of `server_error` or `rate_limit_exceeded`. - - `"run_cancelled"` + - `"server_error"` - - `"run_expired"` + - `"rate_limit_exceeded"` - - `"run_failed"` + - `message: string` + + A human-readable description of the error. - `metadata: Metadata` @@ -233894,740 +233912,722 @@ curl -X DELETE https://api.openai.com/v1/threads/thread_abc123/messages/msg_abc1 Keys are strings with a maximum length of 64 characters. Values are strings with a maximum length of 512 characters. - - `object: "thread.message"` - - The object type, which is always `thread.message`. - - - `"thread.message"` - - - `role: "user" or "assistant"` - - The entity that produced the message. One of `user` or `assistant`. + - `object: "thread.run.step"` - - `"user"` + The object type, which is always `thread.run.step`. - - `"assistant"` + - `"thread.run.step"` - `run_id: string` - The ID of the [run](/docs/api-reference/runs) associated with the creation of this message. Value is `null` when messages are created manually using the create message or create thread endpoints. + The ID of the [run](/docs/api-reference/runs) that this run step is a part of. - - `status: "in_progress" or "incomplete" or "completed"` + - `status: "in_progress" or "cancelled" or "failed" or 2 more` - The status of the message, which can be either `in_progress`, `incomplete`, or `completed`. + The status of the run step, which can be either `in_progress`, `cancelled`, `failed`, `completed`, or `expired`. - `"in_progress"` - - `"incomplete"` + - `"cancelled"` + + - `"failed"` - `"completed"` - - `thread_id: string` + - `"expired"` - The [thread](/docs/api-reference/threads) ID that this message belongs to. + - `step_details: MessageCreationStepDetails or ToolCallsStepDetails` -### Message Deleted + The details of the run step. -- `MessageDeleted object { id, deleted, object }` + - `MessageCreationStepDetails object { message_creation, type }` - - `id: string` + Details of the message creation by the run step. - - `deleted: boolean` + - `message_creation: object { message_id }` - - `object: "thread.message.deleted"` + - `message_id: string` - - `"thread.message.deleted"` + The ID of the message that was created by this run step. -### Message Delta + - `type: "message_creation"` -- `MessageDelta object { content, role }` + Always `message_creation`. - The delta containing the fields that have changed on the Message. + - `"message_creation"` - - `content: optional array of ImageFileDeltaBlock or TextDeltaBlock or RefusalDeltaBlock or ImageURLDeltaBlock` + - `ToolCallsStepDetails object { tool_calls, type }` - The content of the message in array of text and/or images. + Details of the tool call. - - `ImageFileDeltaBlock object { index, type, image_file }` + - `tool_calls: array of CodeInterpreterToolCall or FileSearchToolCall or FunctionToolCall` - References an image [File](/docs/api-reference/files) in the content of a message. + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - - `index: number` + - `CodeInterpreterToolCall object { id, code_interpreter, type }` - The index of the content part in the message. + Details of the Code Interpreter tool call the run step was involved in. - - `type: "image_file"` + - `id: string` - Always `image_file`. + The ID of the tool call. - - `"image_file"` + - `code_interpreter: object { input, outputs }` - - `image_file: optional ImageFileDelta` + The Code Interpreter tool call definition. - - `detail: optional "auto" or "low" or "high"` + - `input: string` - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + The input to the Code Interpreter tool call. - - `"auto"` + - `outputs: array of object { logs, type } or object { image, type }` - - `"low"` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `"high"` + - `CodeInterpreterLogOutput object { logs, type }` - - `file_id: optional string` + Text output from the Code Interpreter tool call as part of a run step. - The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + - `logs: string` - - `TextDeltaBlock object { index, type, text }` + The text output from the Code Interpreter tool call. - The text content that is part of a message. + - `type: "logs"` - - `index: number` + Always `logs`. - The index of the content part in the message. + - `"logs"` - - `type: "text"` + - `CodeInterpreterImageOutput object { image, type }` - Always `text`. + - `image: object { file_id }` - - `"text"` + - `file_id: string` - - `text: optional TextDelta` + The [file](/docs/api-reference/files) ID of the image. - - `annotations: optional array of FileCitationDeltaAnnotation or FilePathDeltaAnnotation` + - `type: "image"` - - `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` + Always `image`. - A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + - `"image"` - - `index: number` + - `type: "code_interpreter"` - The index of the annotation in the text content part. + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `type: "file_citation"` + - `"code_interpreter"` - Always `file_citation`. + - `FileSearchToolCall object { id, file_search, type }` - - `"file_citation"` + - `id: string` - - `end_index: optional number` + The ID of the tool call object. - - `file_citation: optional object { file_id, quote }` + - `file_search: object { ranking_options, results }` - - `file_id: optional string` + For now, this is always going to be an empty object. - The ID of the specific File the citation is from. + - `ranking_options: optional object { ranker, score_threshold }` - - `quote: optional string` + The ranking options for the file search. - The specific quote in the file. + - `ranker: "auto" or "default_2024_08_21"` - - `start_index: optional number` + The ranker to use for the file search. If not specified will use the `auto` ranker. - - `text: optional string` + - `"auto"` - The text in the message content that needs to be replaced. + - `"default_2024_08_21"` - - `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` + - `score_threshold: number` - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `index: number` + - `results: optional array of object { file_id, file_name, score, content }` - The index of the annotation in the text content part. + The results of the file search. - - `type: "file_path"` + - `file_id: string` - Always `file_path`. + The ID of the file that result was found in. - - `"file_path"` + - `file_name: string` - - `end_index: optional number` + The name of the file that result was found in. - - `file_path: optional object { file_id }` + - `score: number` - - `file_id: optional string` + The score of the result. All values must be a floating point number between 0 and 1. - The ID of the file that was generated. + - `content: optional array of object { text, type }` - - `start_index: optional number` + The content of the result that was found. The content is only included if requested via the include query parameter. - `text: optional string` - The text in the message content that needs to be replaced. - - - `value: optional string` + The text content of the file. - The data that makes up the text. + - `type: optional "text"` - - `RefusalDeltaBlock object { index, type, refusal }` + The type of the content. - The refusal content that is part of a message. + - `"text"` - - `index: number` + - `type: "file_search"` - The index of the refusal part in the message. + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `type: "refusal"` + - `"file_search"` - Always `refusal`. + - `FunctionToolCall object { id, function, type }` - - `"refusal"` + - `id: string` - - `refusal: optional string` + The ID of the tool call object. - - `ImageURLDeltaBlock object { index, type, image_url }` + - `function: object { arguments, name, output }` - References an image URL in the content of a message. + The definition of the function that was called. - - `index: number` + - `arguments: string` - The index of the content part in the message. + The arguments passed to the function. - - `type: "image_url"` + - `name: string` - Always `image_url`. + The name of the function. - - `"image_url"` + - `output: string` - - `image_url: optional ImageURLDelta` + The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. - - `detail: optional "auto" or "low" or "high"` + - `type: "function"` - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. + The type of tool call. This is always going to be `function` for this type of tool call. - - `"auto"` + - `"function"` - - `"low"` + - `type: "tool_calls"` - - `"high"` + Always `tool_calls`. - - `url: optional string` + - `"tool_calls"` - The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `thread_id: string` - - `role: optional "user" or "assistant"` + The ID of the [thread](/docs/api-reference/threads) that was run. - The entity that produced the message. One of `user` or `assistant`. + - `type: "message_creation" or "tool_calls"` - - `"user"` + The type of run step, which can be either `message_creation` or `tool_calls`. - - `"assistant"` + - `"message_creation"` -### Message Delta Event + - `"tool_calls"` -- `MessageDeltaEvent object { id, delta, object }` + - `usage: object { completion_tokens, prompt_tokens, total_tokens }` - Represents a message delta i.e. any changed fields on a message during streaming. + Usage statistics related to the run step. This value will be `null` while the run step's status is `in_progress`. - - `id: string` + - `completion_tokens: number` - The identifier of the message, which can be referenced in API endpoints. + Number of completion tokens used over the course of the run step. - - `delta: MessageDelta` + - `prompt_tokens: number` - The delta containing the fields that have changed on the Message. + Number of prompt tokens used over the course of the run step. - - `content: optional array of ImageFileDeltaBlock or TextDeltaBlock or RefusalDeltaBlock or ImageURLDeltaBlock` + - `total_tokens: number` - The content of the message in array of text and/or images. + Total number of tokens used (prompt + completion). - - `ImageFileDeltaBlock object { index, type, image_file }` +### Run Step Delta Event - References an image [File](/docs/api-reference/files) in the content of a message. +- `RunStepDeltaEvent object { id, delta, object }` - - `index: number` + Represents a run step delta i.e. any changed fields on a run step during streaming. - The index of the content part in the message. + - `id: string` - - `type: "image_file"` + The identifier of the run step, which can be referenced in API endpoints. - Always `image_file`. + - `delta: object { step_details }` - - `"image_file"` + The delta containing the fields that have changed on the run step. - - `image_file: optional ImageFileDelta` + - `step_details: optional RunStepDeltaMessageDelta or ToolCallDeltaObject` - - `detail: optional "auto" or "low" or "high"` + The details of the run step. - Specifies the detail level of the image if specified by the user. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `RunStepDeltaMessageDelta object { type, message_creation }` - - `"auto"` + Details of the message creation by the run step. - - `"low"` + - `type: "message_creation"` - - `"high"` + Always `message_creation`. - - `file_id: optional string` + - `"message_creation"` - The [File](/docs/api-reference/files) ID of the image in the message content. Set `purpose="vision"` when uploading the File if you need to later display the file content. + - `message_creation: optional object { message_id }` - - `TextDeltaBlock object { index, type, text }` + - `message_id: optional string` - The text content that is part of a message. + The ID of the message that was created by this run step. - - `index: number` + - `ToolCallDeltaObject object { type, tool_calls }` - The index of the content part in the message. + Details of the tool call. - - `type: "text"` + - `type: "tool_calls"` - Always `text`. + Always `tool_calls`. - - `"text"` + - `"tool_calls"` - - `text: optional TextDelta` + - `tool_calls: optional array of CodeInterpreterToolCallDelta or FileSearchToolCallDelta or FunctionToolCallDelta` - - `annotations: optional array of FileCitationDeltaAnnotation or FilePathDeltaAnnotation` + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - - `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` + - `CodeInterpreterToolCallDelta object { index, type, id, code_interpreter }` - A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + Details of the Code Interpreter tool call the run step was involved in. - `index: number` - The index of the annotation in the text content part. - - - `type: "file_citation"` + The index of the tool call in the tool calls array. - Always `file_citation`. + - `type: "code_interpreter"` - - `"file_citation"` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - - `end_index: optional number` + - `"code_interpreter"` - - `file_citation: optional object { file_id, quote }` + - `id: optional string` - - `file_id: optional string` + The ID of the tool call. - The ID of the specific File the citation is from. + - `code_interpreter: optional object { input, outputs }` - - `quote: optional string` + The Code Interpreter tool call definition. - The specific quote in the file. + - `input: optional string` - - `start_index: optional number` + The input to the Code Interpreter tool call. - - `text: optional string` + - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` - The text in the message content that needs to be replaced. + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - - `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` + - `CodeInterpreterLogs object { index, type, logs }` - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + Text output from the Code Interpreter tool call as part of a run step. - `index: number` - The index of the annotation in the text content part. - - - `type: "file_path"` - - Always `file_path`. - - - `"file_path"` - - - `end_index: optional number` - - - `file_path: optional object { file_id }` + The index of the output in the outputs array. - - `file_id: optional string` + - `type: "logs"` - The ID of the file that was generated. + Always `logs`. - - `start_index: optional number` + - `"logs"` - - `text: optional string` + - `logs: optional string` - The text in the message content that needs to be replaced. + The text output from the Code Interpreter tool call. - - `value: optional string` + - `CodeInterpreterOutputImage object { index, type, image }` - The data that makes up the text. + - `index: number` - - `RefusalDeltaBlock object { index, type, refusal }` + The index of the output in the outputs array. - The refusal content that is part of a message. + - `type: "image"` - - `index: number` + Always `image`. - The index of the refusal part in the message. + - `"image"` - - `type: "refusal"` + - `image: optional object { file_id }` - Always `refusal`. + - `file_id: optional string` - - `"refusal"` + The [file](/docs/api-reference/files) ID of the image. - - `refusal: optional string` + - `FileSearchToolCallDelta object { file_search, index, type, id }` - - `ImageURLDeltaBlock object { index, type, image_url }` + - `file_search: unknown` - References an image URL in the content of a message. + For now, this is always going to be an empty object. - `index: number` - The index of the content part in the message. + The index of the tool call in the tool calls array. - - `type: "image_url"` + - `type: "file_search"` - Always `image_url`. + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `"image_url"` + - `"file_search"` - - `image_url: optional ImageURLDelta` + - `id: optional string` - - `detail: optional "auto" or "low" or "high"` + The ID of the tool call object. - Specifies the detail level of the image. `low` uses fewer tokens, you can opt in to high resolution using `high`. + - `FunctionToolCallDelta object { index, type, id, function }` - - `"auto"` + - `index: number` - - `"low"` + The index of the tool call in the tool calls array. - - `"high"` + - `type: "function"` - - `url: optional string` + The type of tool call. This is always going to be `function` for this type of tool call. - The URL of the image, must be a supported image types: jpeg, jpg, png, gif, webp. + - `"function"` - - `role: optional "user" or "assistant"` + - `id: optional string` - The entity that produced the message. One of `user` or `assistant`. + The ID of the tool call object. - - `"user"` + - `function: optional object { arguments, name, output }` - - `"assistant"` + The definition of the function that was called. - - `object: "thread.message.delta"` + - `arguments: optional string` - The object type, which is always `thread.message.delta`. + The arguments passed to the function. - - `"thread.message.delta"` + - `name: optional string` -### Refusal Content Block + The name of the function. -- `RefusalContentBlock object { refusal, type }` + - `output: optional string` - The refusal content generated by the assistant. + The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. - - `refusal: string` + - `object: "thread.run.step.delta"` - - `type: "refusal"` + The object type, which is always `thread.run.step.delta`. - Always `refusal`. + - `"thread.run.step.delta"` - - `"refusal"` +### Run Step Delta Message Delta -### Refusal Delta Block +- `RunStepDeltaMessageDelta object { type, message_creation }` -- `RefusalDeltaBlock object { index, type, refusal }` + Details of the message creation by the run step. - The refusal content that is part of a message. + - `type: "message_creation"` - - `index: number` + Always `message_creation`. - The index of the refusal part in the message. + - `"message_creation"` - - `type: "refusal"` + - `message_creation: optional object { message_id }` - Always `refusal`. + - `message_id: optional string` - - `"refusal"` + The ID of the message that was created by this run step. - - `refusal: optional string` +### Run Step Include -### Text +- `RunStepInclude = "step_details.tool_calls[*].file_search.results[*].content"` -- `Text object { annotations, value }` + - `"step_details.tool_calls[*].file_search.results[*].content"` - - `annotations: array of FileCitationAnnotation or FilePathAnnotation` +### Tool Call Delta Object - - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` +- `ToolCallDeltaObject object { type, tool_calls }` - A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + Details of the tool call. - - `end_index: number` + - `type: "tool_calls"` - - `file_citation: object { file_id }` + Always `tool_calls`. - - `file_id: string` + - `"tool_calls"` - The ID of the specific File the citation is from. + - `tool_calls: optional array of CodeInterpreterToolCallDelta or FileSearchToolCallDelta or FunctionToolCallDelta` - - `start_index: number` + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - - `text: string` + - `CodeInterpreterToolCallDelta object { index, type, id, code_interpreter }` - The text in the message content that needs to be replaced. + Details of the Code Interpreter tool call the run step was involved in. - - `type: "file_citation"` + - `index: number` - Always `file_citation`. + The index of the tool call in the tool calls array. - - `"file_citation"` + - `type: "code_interpreter"` - - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `"code_interpreter"` - - `end_index: number` + - `id: optional string` - - `file_path: object { file_id }` + The ID of the tool call. - - `file_id: string` + - `code_interpreter: optional object { input, outputs }` - The ID of the file that was generated. + The Code Interpreter tool call definition. - - `start_index: number` + - `input: optional string` - - `text: string` + The input to the Code Interpreter tool call. - The text in the message content that needs to be replaced. + - `outputs: optional array of CodeInterpreterLogs or CodeInterpreterOutputImage` - - `type: "file_path"` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - Always `file_path`. + - `CodeInterpreterLogs object { index, type, logs }` - - `"file_path"` + Text output from the Code Interpreter tool call as part of a run step. - - `value: string` + - `index: number` - The data that makes up the text. + The index of the output in the outputs array. -### Text Content Block + - `type: "logs"` -- `TextContentBlock object { text, type }` + Always `logs`. - The text content that is part of a message. + - `"logs"` - - `text: Text` + - `logs: optional string` - - `annotations: array of FileCitationAnnotation or FilePathAnnotation` + The text output from the Code Interpreter tool call. - - `FileCitationAnnotation object { end_index, file_citation, start_index, 2 more }` + - `CodeInterpreterOutputImage object { index, type, image }` - A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + - `index: number` - - `end_index: number` + The index of the output in the outputs array. - - `file_citation: object { file_id }` + - `type: "image"` - - `file_id: string` + Always `image`. - The ID of the specific File the citation is from. + - `"image"` - - `start_index: number` + - `image: optional object { file_id }` - - `text: string` + - `file_id: optional string` - The text in the message content that needs to be replaced. + The [file](/docs/api-reference/files) ID of the image. - - `type: "file_citation"` + - `FileSearchToolCallDelta object { file_search, index, type, id }` - Always `file_citation`. + - `file_search: unknown` - - `"file_citation"` + For now, this is always going to be an empty object. - - `FilePathAnnotation object { end_index, file_path, start_index, 2 more }` + - `index: number` - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + The index of the tool call in the tool calls array. - - `end_index: number` + - `type: "file_search"` - - `file_path: object { file_id }` + The type of tool call. This is always going to be `file_search` for this type of tool call. - - `file_id: string` + - `"file_search"` - The ID of the file that was generated. + - `id: optional string` - - `start_index: number` + The ID of the tool call object. - - `text: string` + - `FunctionToolCallDelta object { index, type, id, function }` - The text in the message content that needs to be replaced. + - `index: number` - - `type: "file_path"` + The index of the tool call in the tool calls array. - Always `file_path`. + - `type: "function"` - - `"file_path"` + The type of tool call. This is always going to be `function` for this type of tool call. - - `value: string` + - `"function"` - The data that makes up the text. + - `id: optional string` - - `type: "text"` + The ID of the tool call object. - Always `text`. + - `function: optional object { arguments, name, output }` - - `"text"` + The definition of the function that was called. -### Text Content Block Param + - `arguments: optional string` -- `TextContentBlockParam object { text, type }` + The arguments passed to the function. - The text content that is part of a message. + - `name: optional string` - - `text: string` + The name of the function. - Text content to be sent to the model + - `output: optional string` - - `type: "text"` + The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. - Always `text`. +### Tool Calls Step Details - - `"text"` +- `ToolCallsStepDetails object { tool_calls, type }` -### Text Delta + Details of the tool call. -- `TextDelta object { annotations, value }` + - `tool_calls: array of CodeInterpreterToolCall or FileSearchToolCall or FunctionToolCall` - - `annotations: optional array of FileCitationDeltaAnnotation or FilePathDeltaAnnotation` + An array of tool calls the run step was involved in. These can be associated with one of three types of tools: `code_interpreter`, `file_search`, or `function`. - - `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` + - `CodeInterpreterToolCall object { id, code_interpreter, type }` - A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + Details of the Code Interpreter tool call the run step was involved in. - - `index: number` + - `id: string` - The index of the annotation in the text content part. + The ID of the tool call. - - `type: "file_citation"` + - `code_interpreter: object { input, outputs }` - Always `file_citation`. + The Code Interpreter tool call definition. - - `"file_citation"` + - `input: string` - - `end_index: optional number` + The input to the Code Interpreter tool call. - - `file_citation: optional object { file_id, quote }` + - `outputs: array of object { logs, type } or object { image, type }` - - `file_id: optional string` + The outputs from the Code Interpreter tool call. Code Interpreter can output one or more items, including text (`logs`) or images (`image`). Each of these are represented by a different object type. - The ID of the specific File the citation is from. + - `CodeInterpreterLogOutput object { logs, type }` - - `quote: optional string` + Text output from the Code Interpreter tool call as part of a run step. - The specific quote in the file. + - `logs: string` - - `start_index: optional number` + The text output from the Code Interpreter tool call. - - `text: optional string` + - `type: "logs"` - The text in the message content that needs to be replaced. + Always `logs`. - - `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` + - `"logs"` - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `CodeInterpreterImageOutput object { image, type }` - - `index: number` + - `image: object { file_id }` - The index of the annotation in the text content part. + - `file_id: string` - - `type: "file_path"` + The [file](/docs/api-reference/files) ID of the image. - Always `file_path`. + - `type: "image"` - - `"file_path"` + Always `image`. - - `end_index: optional number` + - `"image"` - - `file_path: optional object { file_id }` + - `type: "code_interpreter"` - - `file_id: optional string` + The type of tool call. This is always going to be `code_interpreter` for this type of tool call. - The ID of the file that was generated. + - `"code_interpreter"` - - `start_index: optional number` + - `FileSearchToolCall object { id, file_search, type }` - - `text: optional string` + - `id: string` - The text in the message content that needs to be replaced. + The ID of the tool call object. - - `value: optional string` + - `file_search: object { ranking_options, results }` - The data that makes up the text. + For now, this is always going to be an empty object. -### Text Delta Block + - `ranking_options: optional object { ranker, score_threshold }` -- `TextDeltaBlock object { index, type, text }` + The ranking options for the file search. - The text content that is part of a message. + - `ranker: "auto" or "default_2024_08_21"` - - `index: number` + The ranker to use for the file search. If not specified will use the `auto` ranker. - The index of the content part in the message. + - `"auto"` - - `type: "text"` + - `"default_2024_08_21"` - Always `text`. + - `score_threshold: number` - - `"text"` + The score threshold for the file search. All values must be a floating point number between 0 and 1. - - `text: optional TextDelta` + - `results: optional array of object { file_id, file_name, score, content }` - - `annotations: optional array of FileCitationDeltaAnnotation or FilePathDeltaAnnotation` + The results of the file search. - - `FileCitationDeltaAnnotation object { index, type, end_index, 3 more }` + - `file_id: string` - A citation within the message that points to a specific quote from a specific File associated with the assistant or the message. Generated when the assistant uses the "file_search" tool to search files. + The ID of the file that result was found in. - - `index: number` + - `file_name: string` - The index of the annotation in the text content part. + The name of the file that result was found in. - - `type: "file_citation"` + - `score: number` - Always `file_citation`. + The score of the result. All values must be a floating point number between 0 and 1. - - `"file_citation"` + - `content: optional array of object { text, type }` - - `end_index: optional number` + The content of the result that was found. The content is only included if requested via the include query parameter. - - `file_citation: optional object { file_id, quote }` + - `text: optional string` - - `file_id: optional string` + The text content of the file. - The ID of the specific File the citation is from. + - `type: optional "text"` - - `quote: optional string` + The type of the content. - The specific quote in the file. + - `"text"` - - `start_index: optional number` + - `type: "file_search"` - - `text: optional string` + The type of tool call. This is always going to be `file_search` for this type of tool call. - The text in the message content that needs to be replaced. + - `"file_search"` - - `FilePathDeltaAnnotation object { index, type, end_index, 3 more }` + - `FunctionToolCall object { id, function, type }` - A URL for the file that's generated when the assistant used the `code_interpreter` tool to generate a file. + - `id: string` - - `index: number` + The ID of the tool call object. - The index of the annotation in the text content part. + - `function: object { arguments, name, output }` - - `type: "file_path"` + The definition of the function that was called. - Always `file_path`. + - `arguments: string` - - `"file_path"` + The arguments passed to the function. - - `end_index: optional number` + - `name: string` - - `file_path: optional object { file_id }` + The name of the function. - - `file_id: optional string` + - `output: string` - The ID of the file that was generated. + The output of the function. This will be `null` if the outputs have not been [submitted](/docs/api-reference/runs/submitToolOutputs) yet. - - `start_index: optional number` + - `type: "function"` - - `text: optional string` + The type of tool call. This is always going to be `function` for this type of tool call. - The text in the message content that needs to be replaced. + - `"function"` - - `value: optional string` + - `type: "tool_calls"` - The data that makes up the text. + Always `tool_calls`. + + - `"tool_calls"`